diff --git a/docs/FONTS.md b/docs/FONTS.md index 514af0799..9b783dcdc 100644 --- a/docs/FONTS.md +++ b/docs/FONTS.md @@ -12,6 +12,7 @@ In the [misc/fonts/](https://github.com/ocornut/imgui/tree/master/misc/fonts) fo ## Index - [Troubleshooting](#troubleshooting) +- [New! Dynamic Fonts system in 1.92 (March 2025)](#new-dynamic-fonts-system-in-192-march-2025) - [How should I handle DPI in my application?](#how-should-i-handle-dpi-in-my-application) - [Fonts Loading Instructions](#fonts-loading-instructions) - [Loading Font Data from Memory](#loading-font-data-from-memory) @@ -43,6 +44,8 @@ See [About UTF-8 Encoding](#about-utf-8-encoding). Use the encoding viewer to co ### (3) Missing glyph ranges. +πŸ†• **Since 1.92, with an up to date backend: specifying glyph ranges is necessary.** + You need to load a font with explicit glyph ranges if you want to use non-ASCII characters. See [Fonts Loading Instructions](#fonts-loading-instructions). Use [Debug Tools](#debug-tools) confirm loaded fonts and loaded glyph ranges. This is a current constraint of Dear ImGui (which we will lift in the future): when loading a font you need to specify which characters glyphs to load. @@ -50,6 +53,8 @@ All loaded fonts glyphs are rendered into a single texture atlas ahead of time. ### (4) Font atlas texture fails to upload to GPU. +πŸ†• **Since 1.92, with an up to date backend: atlas is built incrementally and dynamically resized, this is less likely to happen** + This is often of byproduct of point 3. If you have large number of glyphs or multiple fonts, the texture may become too big for your graphics API. **The typical result of failing to upload a texture is if every glyph or everything appears as empty white rectangles.** Mind the fact that some graphics drivers have texture size limitation. If you are building a PC application, mind the fact that your users may use hardware with lower limitations than yours. ![empty squares](https://github.com/user-attachments/assets/68b50fb5-8b9d-4c38-baec-6ac384f06d26) @@ -63,6 +68,22 @@ Some solutions: Future versions of Dear ImGui should solve this problem. +##### [Return to Index](#index) + +--------------------------------------- + +## New! Dynamic Fonts system in 1.92 (March 2025+) + +v1.92 will introduce a newer, dynamic font system. It requires backend to support the `ImGuiBackendFlags_HasTextures` feature: +- Users of icons, Asian and non-English languages do not need to pre-build all glyphs ahead of time. Saving on loading time, memory, and also reducing issues with missing glyphs. Specifying glyph ranges is not needed anymore. +- PushFontSize() may be used anytime to change font size. +- Packing custom rectangles is more convenient as pixels may be written to immediately. +- Any update to fonts previously required backend specific calls to re-upload the texture, and said calls were not portable across backends. It is now possible to scale fonts etc. in a way that doesn't require you to make backend-specific calls. +- It is possible to plug a custom loader/backend to any font source. + +See [#8465](https://github.com/ocornut/imgui/issues/8465) for more details. + + ##### [Return to Index](#index) --------------------------------------- @@ -131,6 +152,8 @@ io.Fonts->Build(); **Add a fourth parameter to bake specific font ranges only:** +πŸ†• **Since 1.92, with an up to date backend: specifying glyph ranges is necessary. All the GetGlyphRangesXXX() functions are marked obsolete.** + ```cpp // Basic Latin, Extended Latin io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, nullptr, io.Fonts->GetGlyphRangesDefault()); @@ -145,10 +168,20 @@ See [Using Custom Glyph Ranges](#using-custom-glyph-ranges) section to create yo **Example loading and using a Japanese font:** +πŸ†• **Since 1.92, with an up to date backend:** + +```cpp +ImGuiIO& io = ImGui::GetIO(); +io.Fonts->AddFontFromFileTTF("NotoSansCJKjp-Medium.otf", 20.0f); +``` + +**Before 1.92, or without an up to date backend:** + ```cpp ImGuiIO& io = ImGui::GetIO(); io.Fonts->AddFontFromFileTTF("NotoSansCJKjp-Medium.otf", 20.0f, nullptr, io.Fonts->GetGlyphRangesJapanese()); ``` + ```cpp ImGui::Text(u8"γ“γ‚“γ«γ‘γ―οΌγƒ†γ‚Ήγƒˆ %d", 123); if (ImGui::Button(u8"ロード")) @@ -215,6 +248,8 @@ To refer to the icon UTF-8 codepoints from your C++ code, you may use those head So you can use `ICON_FA_SEARCH` as a string that will render as a "Search" icon. +πŸ†• **Since 1.92, with an up to date backend: specifying glyph ranges is necessary. You can omit this parameter.** + Example Setup: ```cpp // Merge icons into default tool font @@ -289,6 +324,8 @@ io.Fonts->AddFontFromFileTTF("C:\\Windows\\Fonts\\seguiemj.ttf", 16.0f, &cfg, ra ## Using Custom Glyph Ranges +πŸ†• **Since 1.92, with an up to date backend: specifying glyph ranges is necessary, so this is not needed.** + You can use the `ImFontGlyphRangesBuilder` helper to create glyph ranges based on text input. For example: for a game where your script is known, if you can feed your entire script to it and only build the characters the game needs. ```cpp ImVector ranges; @@ -308,6 +345,15 @@ io.Fonts->Build(); // Build the atlas while ## Using Custom Colorful Icons +πŸ†• **Since 1.92, with an up to date backend: this system has been revamped.** + +TL;DR; With the new system, it is recommended that you create a custom `ImFontLoader` and register your fonts with it. +`AddCustomRectFontGlyph()` has been obsolete because its API does not make much sense with resizable fonts. + +You can ask questions in [#8466](https://github.com/ocornut/imgui/issues/8466). + +πŸ†• **Before 1.92:** + As an alternative to rendering colorful glyphs using imgui_freetype with `ImGuiFreeTypeBuilderFlags_LoadColor`, you may allocate your own space in the texture atlas and write yourself into it. **(This is a BETA api, use if you are familiar with dear imgui and with your rendering backend)** - You can use the `ImFontAtlas::AddCustomRect()` and `ImFontAtlas::AddCustomRectFontGlyph()` api to register rectangles that will be packed into the font atlas texture. Register them before building the atlas, then call Build()`. diff --git a/imgui.h b/imgui.h index f03a20306..8f01ff7ef 100644 --- a/imgui.h +++ b/imgui.h @@ -3553,11 +3553,13 @@ struct ImFontAtlas // Glyph Ranges //------------------------------------------- + // Since 1.92: specifying glyph ranges is only useful/necessary if your backend doesn't support ImGuiBackendFlags_HasTextures! + IMGUI_API const ImWchar* GetGlyphRangesDefault(); // Basic Latin, Extended Latin +#ifndef IMGUI_DISABLE_OBSOLETE_FUNCTIONS // Helpers to retrieve list of common Unicode ranges (2 value per range, values are inclusive, zero-terminated list) // NB: Make sure that your string are UTF-8 and NOT in your local code page. // Read https://github.com/ocornut/imgui/blob/master/docs/FONTS.md/#about-utf-8-encoding for details. // NB: Consider using ImFontGlyphRangesBuilder to build glyph ranges from textual data. - IMGUI_API const ImWchar* GetGlyphRangesDefault(); // Basic Latin, Extended Latin IMGUI_API const ImWchar* GetGlyphRangesGreek(); // Default + Greek and Coptic IMGUI_API const ImWchar* GetGlyphRangesKorean(); // Default + Korean characters IMGUI_API const ImWchar* GetGlyphRangesJapanese(); // Default + Hiragana, Katakana, Half-Width, Selection of 2999 Ideographs @@ -3566,6 +3568,7 @@ struct ImFontAtlas IMGUI_API const ImWchar* GetGlyphRangesCyrillic(); // Default + about 400 Cyrillic characters IMGUI_API const ImWchar* GetGlyphRangesThai(); // Default + Thai characters IMGUI_API const ImWchar* GetGlyphRangesVietnamese(); // Default + Vietnamese characters +#endif //------------------------------------------- // [ALPHA] Custom Rectangles/Glyphs API diff --git a/imgui_draw.cpp b/imgui_draw.cpp index d51ae9e50..c99dbb5a8 100644 --- a/imgui_draw.cpp +++ b/imgui_draw.cpp @@ -4579,6 +4579,7 @@ const ImFontLoader* ImFontAtlasGetFontLoaderForStbTruetype() // [SECTION] ImFontAtlas: glyph ranges helpers //------------------------------------------------------------------------- // - GetGlyphRangesDefault() +// Obsolete functions since 1.92: // - GetGlyphRangesGreek() // - GetGlyphRangesKorean() // - GetGlyphRangesChineseFull() @@ -4600,6 +4601,7 @@ const ImWchar* ImFontAtlas::GetGlyphRangesDefault() return &ranges[0]; } +#ifndef IMGUI_DISABLE_OBSOLETE_FUNCTIONS const ImWchar* ImFontAtlas::GetGlyphRangesGreek() { static const ImWchar ranges[] = @@ -4849,6 +4851,7 @@ const ImWchar* ImFontAtlas::GetGlyphRangesVietnamese() }; return &ranges[0]; } +#endif // #ifndef IMGUI_DISABLE_OBSOLETE_FUNCTIONS //----------------------------------------------------------------------------- // [SECTION] ImFontGlyphRangesBuilder