Add HarfBuzz Text Shaping and Font Fallback Support (#3611)

Co-authored-by: alan wei chen <[email protected]>

Author: stefankarschti

.gitmodules

@@ -37,6 +37,12 @@
 [submodule "platform/windows/vendor/vcpkg"]
 	path = platform/windows/vendor/vcpkg
 	url = https://github.com/microsoft/vcpkg.git
+[submodule "vendor/harfbuzzFreetype/freetype"]
+	path = vendor/freetype
+  url=https://github.com/freetype/freetype.git
+[submodule "vendor/harfbuzzFreetype/harfbuzz"]
+	path = vendor/harfbuzz
+  url=https://github.com/harfbuzz/harfbuzz
 [submodule "vendor/boost"]
 	path = vendor/boost
 	url = https://github.com/maplibre/maplibre-gl-native-boost.git

BUILD.bazel

@@ -22,6 +22,7 @@ load(
     "MLN_OPENGL_SOURCE",
     "MLN_PRIVATE_GENERATED_STYLE_HEADERS",
     "MLN_PUBLIC_GENERATED_STYLE_HEADERS",
+    "MLN_SHAPING_HARFBUZZ_SRCS",
 )
 load("//bazel:flags.bzl", "CPP_FLAGS", "MAPLIBRE_FLAGS")
 
@@ -85,6 +86,9 @@ cc_library(
         ":drawable_renderer": MLN_OPENGL_SOURCE + MLN_DRAWABLES_SOURCE + MLN_DRAWABLES_GL_SOURCE,
         ":metal_renderer": MLN_DRAWABLES_SOURCE + MLN_DRAWABLES_MTL_SOURCE,
         "//conditions:default": [],
+    }) + select({
+        "//:harfbuzz_text_shaping": MLN_SHAPING_HARFBUZZ_SRCS,
+        "//conditions:default": [],
     }),
     hdrs = MLN_LAYER_PLUGIN_HEADERS + MLN_CORE_HEADERS + select({
         ":drawable_renderer": MLN_OPENGL_HEADERS + MLN_DRAWABLES_HEADERS + MLN_DRAWABLES_GL_HEADERS,
@@ -102,6 +106,9 @@ cc_library(
     }) + select({
         "@platforms//os:ios": ["GLES_SILENCE_DEPRECATION=1"],
         "//conditions:default": [],
+    }) + select({
+        "//:harfbuzz_text_shaping": ["MLN_TEXT_SHAPING_HARFBUZZ=1"],
+        "//conditions:default": [],
     }),
     includes = [
         "include",
@@ -111,6 +118,12 @@ cc_library(
             "vendor/metal-cpp",
         ],
         "//conditions:default": [],
+    }) + select({
+        "//:harfbuzz_text_shaping": [
+            "vendor/freetype/include",
+            "vendor/harfbuzz/src",
+        ],
+        "//conditions:default": [],
     }),
     local_defines = [
         r"MLN_VERSION_REV=\"standalone\"",
@@ -147,6 +160,12 @@ cc_library(
             "//vendor:metal-cpp",
         ],
         "//conditions:default": [],
+    }) + select({
+        ":harfbuzz_text_shaping": [
+            "//vendor:freetype",
+            "//vendor:harfbuzz",
+        ],
+        "//conditions:default": [],
     }) + select({
         ":rust": [
             "//rustutils:rustutilslib",
@@ -182,6 +201,31 @@ config_setting(
     },
 )
 
+# Selects the shaping implementation to utilize in the core
+
+string_flag(
+    name = "shaping",
+    build_setting_default = "harfbuzz",
+    values = [
+        "legacy",
+        "harfbuzz",
+    ],
+)
+
+config_setting(
+    name = "harfbuzz_text_shaping",
+    flag_values = {
+        ":shaping": "harfbuzz",
+    },
+)
+
+config_setting(
+    name = "legacy_text_shaping",
+    flag_values = {
+        ":shaping": "legacy",
+    },
+)
+
 bool_flag(
     name = "use_rust",
     build_setting_default = False,

CMakeLists.txt

@@ -16,6 +16,7 @@ option(MLN_WITH_WERROR "Make all compilation warnings errors" ON)
 option(MLN_USE_UNORDERED_DENSE "Use ankerl dense containers for performance" ON)
 option(MLN_USE_TRACY "Enable Tracy instrumentation" OFF)
 option(MLN_USE_RUST "Use components in Rust" OFF)
+option(MLN_TEXT_SHAPING_HARFBUZZ "Use haffbuzz to shape complex text" ON)
 option(MLN_CORE_INCLUDE_DEPS "Include depdendencies in static build of core" OFF)
 option(MLN_CREATE_AUTORELEASEPOOL "Create autoreleasepool in render loop" OFF)
 
@@ -1333,6 +1334,35 @@ list(APPEND
         ${PROJECT_SOURCE_DIR}/src/mbgl/style/layers/custom_drawable_layer.cpp
 )
 
+# Harfbuzz text shaping
+set(SHAPE_TARGETS, "")
+list(APPEND
+    SRC_FILES
+        # Base text shaping files, which are always included. They don't depend on HarfBuzz if MLN_TEXT_SHAPING_HARFBUZZ is OFF.
+        ${PROJECT_SOURCE_DIR}/src/mbgl/text/harfbuzz.cpp
+        ${PROJECT_SOURCE_DIR}/src/mbgl/text/harfbuzz.hpp
+)
+if (MLN_TEXT_SHAPING_HARFBUZZ)
+    message(STATUS "Configuring with HarfBuzz text shaping")
+    list(APPEND
+        SRC_FILES
+        ${PROJECT_SOURCE_DIR}/src/mbgl/text/harfbuzz_impl.cpp
+        ${PROJECT_SOURCE_DIR}/src/mbgl/text/harfbuzz_impl.hpp
+        ${PROJECT_SOURCE_DIR}/src/mbgl/text/freetype.cpp
+        ${PROJECT_SOURCE_DIR}/src/mbgl/text/freetype.hpp
+    )
+    target_compile_definitions(
+        mbgl-core
+        PRIVATE MLN_TEXT_SHAPING_HARFBUZZ=1
+    )
+    include(${PROJECT_SOURCE_DIR}/vendor/freetype.cmake)
+    include(${PROJECT_SOURCE_DIR}/vendor/harfbuzz.cmake)
+    set(SHAPE_TARGETS
+        freetype
+        harfbuzz
+    )
+endif()
+
 target_sources(
     mbgl-core PRIVATE
     ${INCLUDE_FILES}
@@ -1436,6 +1466,7 @@ target_link_libraries(
         mbgl-vendor-wagyu
         $<$<BOOL:${MLN_WITH_METAL}>:mbgl-vendor-metal-cpp>
         $<IF:$<BOOL:${MLN_USE_RUST}>,mbgl-rustutils,mbgl-vendor-csscolorparser>
+        ${SHAPE_TARGETS} # from harfbuzz.cmake
     PUBLIC
         MapLibreNative::Base
         MapLibreNative::Base::Extras::expected-lite
@@ -1476,6 +1507,7 @@ set(EXPORT_TARGETS
     mbgl-vendor-wagyu
     mbgl-vendor-metal-cpp
     unordered_dense
+    ${SHAPE_TARGETS} # from harfbuzz.cmake
 )
 
 if(MLN_USE_RUST)

bazel/core.bzl

@@ -489,6 +489,8 @@ MLN_CORE_SOURCE = [
     "src/mbgl/text/shaping.hpp",
     "src/mbgl/text/tagged_string.cpp",
     "src/mbgl/text/tagged_string.hpp",
+    "src/mbgl/text/harfbuzz.cpp",
+    "src/mbgl/text/harfbuzz.hpp",
     "src/mbgl/tile/custom_geometry_tile.cpp",
     "src/mbgl/tile/custom_geometry_tile.hpp",
     "src/mbgl/tile/geojson_tile.cpp",
@@ -1096,3 +1098,10 @@ MLN_DRAWABLES_MTL_HEADERS = [
     "include/mbgl/style/layers/mtl/custom_layer_render_parameters.hpp",
     "include/mbgl/shaders/mtl/widevector.hpp",
 ]
+
+MLN_SHAPING_HARFBUZZ_SRCS = [
+    "src/mbgl/text/freetype.hpp",
+    "src/mbgl/text/freetype.cpp",
+    "src/mbgl/text/harfbuzz_impl.hpp",
+    "src/mbgl/text/harfbuzz_impl.cpp",
+]

include/mbgl/storage/resource.hpp

@@ -82,6 +82,7 @@ class Resource {
     static Resource glyphs(const std::string& urlTemplate,
                            const FontStack& fontStack,
                            const std::pair<uint16_t, uint16_t>& glyphRange);
+    static Resource fontFace(const std::string& url);
     static Resource spriteImage(const std::string& base, float pixelRatio);
     static Resource spriteJSON(const std::string& base, float pixelRatio);
     static Resource image(const std::string& url);

include/mbgl/text/glyph.hpp

@@ -18,7 +18,40 @@
 
 namespace mbgl {
 
-using GlyphID = char16_t;
+union GlyphID {
+    char32_t hash;
+    struct {
+        char16_t code;
+        GlyphIDType type;
+    } complex;
+
+    GlyphID(int codepoint) {
+        complex.type = FontPBF;
+        complex.code = codepoint;
+    }
+    GlyphID(uint32_t codepoint) {
+        complex.type = FontPBF;
+        complex.code = codepoint;
+    }
+    GlyphID(char16_t codepoint) {
+        complex.type = FontPBF;
+        complex.code = codepoint;
+    }
+
+    GlyphID(char16_t index, GlyphIDType t) {
+        complex.type = t;
+        complex.code = index;
+    }
+
+    operator char16_t() { return complex.code; }
+    operator char32_t() { return hash; }
+    bool operator<(const GlyphID &other) const { return hash < other.hash; }
+    bool operator>(const GlyphID &other) const { return hash > other.hash; }
+
+    bool operator<(const uint16_t &other) const { return hash < other; }
+    bool operator>(const uint16_t &other) const { return hash > other; }
+};
+
 using GlyphIDs = std::set<GlyphID>;
 
 // Note: this only works for the BMP
@@ -32,7 +65,7 @@ struct GlyphMetrics {
     uint32_t advance = 0;
 };
 
-inline bool operator==(const GlyphMetrics& lhs, const GlyphMetrics& rhs) {
+inline bool operator==(const GlyphMetrics &lhs, const GlyphMetrics &rhs) {
     return lhs.width == rhs.width && lhs.height == rhs.height && lhs.left == rhs.left && lhs.top == rhs.top &&
            lhs.advance == rhs.advance;
 }
@@ -114,7 +147,7 @@ class Shaping {
     float right = 0;
     WritingModeType writingMode;
     explicit operator bool() const {
-        return std::ranges::any_of(positionedLines, [](const auto& line) { return !line.positionedGlyphs.empty(); });
+        return std::ranges::any_of(positionedLines, [](const auto &line) { return !line.positionedGlyphs.empty(); });
     }
     // The y offset *should* be part of the font metadata.
     static constexpr int32_t yOffset = -17;
@@ -128,7 +161,50 @@ enum class WritingModeType : uint8_t {
     Vertical = 1 << 1,
 };
 
-using GlyphDependencies = std::map<FontStack, GlyphIDs>;
+// style defined faces
+struct FontFace {
+    using Range = std::pair<uint32_t, uint32_t>;
+    GlyphIDType type;          // an unique glyph id
+    std::string name;          // font face name
+    std::string url;           // font file url
+    std::vector<Range> ranges; // unicode ranges
+
+    FontFace() = default;
+    FontFace(const std::string &name_, const std::string &url_, const std::vector<Range> &ranges_)
+        : type(FontPBF),
+          name(name_),
+          url(url_),
+          ranges(ranges_) {}
+
+    FontFace(const std::string &name_, const std::string &url_, std::vector<Range> &&ranges_)
+        : type(FontPBF),
+          name(name_),
+          url(url_),
+          ranges(std::move(ranges_)) {}
+
+    auto valid() const -> bool { return !name.empty() && !url.empty() && !ranges.empty(); }
+};
+
+using FontFaces = std::vector<FontFace>;
+
+struct HBShapeRequest {
+    std::u16string str;
+    FontStack fontStack;
+    GlyphIDType type;
+
+    HBShapeRequest(const std::u16string &str_, const FontStack &fontStack_, GlyphIDType type_)
+        : str(str_),
+          fontStack(fontStack_),
+          type(type_) {}
+};
+
+using HBShapeRequests = std::map<FontStack, std::map<GlyphIDType, std::set<std::u16string>>>;
+
+struct GlyphDependencies {
+    std::map<FontStack, GlyphIDs> glyphs;
+    HBShapeRequests shapes;
+};
+
 using GlyphRangeDependencies = std::map<FontStack, std::unordered_set<GlyphRange>>;
 
 struct GlyphPosition {

include/mbgl/text/glyph_range.hpp

@@ -4,10 +4,30 @@
 #include <cstdint>
 #include <unordered_set>
 #include <mbgl/util/hash.hpp>
+#include <mbgl/util/font_stack.hpp>
 
 namespace mbgl {
 
-using GlyphRange = std::pair<uint16_t, uint16_t>;
+enum GlyphIDType : uint16_t {
+    FontPBF = 0x00,
+};
+
+GlyphIDType genNewGlyphIDType(const std::string &url,
+                              const FontStack &fontStack,
+                              const std::vector<std::pair<uint32_t, uint32_t>> &pairs);
+
+class GlyphRange {
+public:
+    uint16_t first = 0;
+    uint16_t second = 0;
+
+    GlyphIDType type = GlyphIDType::FontPBF;
+
+    GlyphRange(uint32_t first_, uint32_t second_, GlyphIDType type_ = FontPBF);
+
+    bool operator==(const GlyphRange &other) const;
+    bool operator<(const GlyphRange &other) const;
+};
 
 constexpr uint32_t GLYPHS_PER_GLYPH_RANGE = 256;
 constexpr uint32_t GLYPH_RANGES_PER_FONT_STACK = 256;
@@ -20,7 +40,7 @@ namespace std {
 
 template <>
 struct hash<mbgl::GlyphRange> {
-    std::size_t operator()(const mbgl::GlyphRange& range) const { return mbgl::util::hash(range.first, range.second); }
+    std::size_t operator()(const mbgl::GlyphRange &range) const { return mbgl::util::hash(range.first, range.second); }
 };
 
 } // namespace std