forked from Green-Sky/tomato
Green Sky
8de4c4b301
cb16568fca5 Version 1.91.3 8db126188df Fixed static analyser warning. Amend b3c8747 3d399bcecab Docs: amend docs to explain case of using multiple overlayed ButtonBehavior(). (#8030, #7961, #7669) b3c87475a5a Drags, Slider: added ImGuiSliderFlags_ClampOnInput, ImGuiSliderFlags_ClampZeroRange. (#7968, #3361, #76) 5109a77f697 Tooltips: Tooltips triggered from touch inputs are positionned above the item. (#8036) 014b722963f Tooltips, Drag and Drop: Stabilized name of drag and drop tooltip window. (#8036) f0575411c01 Tooltips, Drag and Drop: Fixed an issue where the fallback drag and drop payload tooltip appeared during drag and drop release. 004f03945f3 TabBar: added TabBarQueueFocus() by name for non-docking tab bars. (#8029, #6681) 655fcf82870 TabBar: added TabBarQueueFocus() by name for non-docking tab bars. (#8029, #6681) 03f007d4cd1 Comments (#1651) 29cff2be068 Silence PVS Studio static analyzer false positives. ba14c70b020 Comments. Fixed warnings. 199a44e31e2 Error Handling: fixed not rewinding to recorded tree and id stack size (#1651) 30c29d291fb Error Handling: enabled experimental recovery systems. (#1651, #5654) 8776678a462 Error Handling: replaced log callback in recovery functions with calls to IM_ASSERT_USER_ERROR(). (#1651, #5654) 718a594b1e1 Error Handling: rewired asserts in PopID(), PopFont(), PopItemFlag(), EndDisabled(), PopTextWrapPos(), PopFocusScope(), PopItemWidth() to use IM_ASSERT_USER_ERROR(). (#1651, #5654) 2360061520e Error Handling, Debug Log: added IMGUI_DEBUG_LOG_ERROR() with special handling. (#5855, #1651, #5654) 26785fd8731 Internals: NewFrame: move the window reset loop higher up, namely before UpdateHoveredWindowAndCaptureFlags() -> FindHoveredWindowEx(). 797101a882b Windows: BeginChild(): made it possible to call SetNextWindowSize() on a child window using ImGuiChildFlags_ResizeX/ImGuiChildFlags_ResizeY. (#1710, #8020) 9644c511835 Error handling: rework error tooltip logic (will be reused by upcoming feature). (#7961, #7669, #1651) d0107f5da23 Internals: misc tweaks to facilitate branch merging. 726aad8e088 Refactor: moved ImGuiContext contructor to imgui.cpp 44a73be6eaf TestEngine: log calls don't need testing hook active. bc77041b578 Error Handling: fixed an issue ErrorCheckEndWindowRecover() when aborting in a child inside a tab bar. (#1651) 7f81fbc5426 Backends: WGPU: Fix new WGPUStringView breaks shader compilation. (#8009, #8010) fb410463e6a Scrollbar: added io.ConfigScrollbarScrollByPage setting. (#8002, #7328) a727332e772 Scrollbar: Shift+Click always use absolute positionning scroll. (#8002, #7328) 4aeae5d7189 Error check: fixed build when using IMGUI_DISABLE_DEBUG_TOOLS. d0750ee4e7d Error check: clarified that carriage returns are emitted by our code. Added helper default callback. Comments. (#1651) 0af2c4ef765 Backends: SDL3: Update for API changes: SDL_bool removal. SDL_INIT_TIMER removal. (#7999) faca859043c Version 1.91.3 WIP a9f72ab6818 Version 1.91.2 cfae5ac71b9 Backends: make ImGui_ImplSDL2_KeyEventToImGuiKey(), ImGui_ImplSDL3_KeyEventToImGuiKey(), ImGui_ImplGlfw_KeyToImGuiKey(), ImGui_ImplWin32_KeyEventToImGuiKey(), ImGui_ImplAllegro5_KeyCodeToImGuiKey(), ImGui_ImplOSX_KeyCodeToImGuiKey(), non-static. (#7997) f7ba6453980 InputText: fixed not filling callback's SelectionEnd. (#7925) e648dbb59d2 Tables: fixed auto-width columns when using synced-instances of same table. (#7218) 6aade6912a1 Inputs: SetNextItemShortcut() with ImGuiInputFlags_Tooltip doesn't show tooltip when item is active. dad9f45e3ed Windows: fixed an issue where double-click to collapse could be triggered even while another item is active. (#7841, #7369) 71714eab536 Tables: fixed assertion related to inconsistent outer clipping when sizes are not rounded. (#7957) 11fba027e50 Tables: using table->InnerClipRect more consistently. Fixes an assertion with tables with borders when clipped by parent. (#6765, #3752, #7428) 6ce26ef11d5 AddFont: added assert to better detect uninitialized struct. (#7993) 08b1496b7e5 Backends: Win32: fixed an issue where a viewport destroyed while clicking would hog mouse tracking and temporary lead to incorrect update of HoveredWindow. (#7971) 1ac162f2b08 Backends: WGPU: add IMGUI_IMPL_WEBGPU_BACKEND_DAWN/IMGUI_IMPL_WEBGPU_BACKEND_WGPU to support more targets. (#7977, #7969, #6602, #6188, #7523) 4925695ae88 InputText: optimize InputTextCalcTextLenAndLineCount() for inactive multiline path. (#7925) 7ac50bf77d0 InputText: more tidying up of selection search loop. aef07aea274 InputText: minor tidying up of selection search loop (no need to imply it runs in single line mode) b53d91a4c40 InputText: optimization for large text: using memchr() instead of strchr() shaves 0.2 ms on 865k multi-line text case. Approximately 20%. (#7925) 510b6adc9bb CI: disable month-long PVS Studio warning about expiring licence. dab63231d88 Misc: Made it accepted to call SetMouseCursor() with any out-of-bound value, as a way to allow hacking in custom cursors if desirable. 4d00bf8add4 MultiSelect+Tables: fixed an issue where box-select would skip items while drag-scrolling in a table with outer borders. (#7970, #7821). 6dcb7be35f8 CI: amend build tests for emscripten (#7965) ac2ad79812e Backends: GLFW+Emscripten: use OSX behaviors automatically when using contrib glfw port. (#7965, #7915) 52a6ab44b1f Doc: Fix typo. (#7974) dc6346b763e Fonts: fixed ellipsis "..." rendering width miscalculation bug introduced in 1.91.0. (#7976) 8807b01b288 InputText: amends: now can use memchr()/strchr() for line counting. Much faster! (#7925) 19accb14a9e InputText: amends: fixed undo-stack reconcile. fixed metrics crash. fixes character filtering. (#7925) 3d1e593b5b1 InputText: amends: fixed next/prev word implementation. (#7925) e240bc151a3 InputText: amends: add note about STB_TEXTEDIT_GETCHAR. tweak InputTextCalcTextSize() to use similar debug-friendly logic as ImFont:CalcTextSizeA(). misc small tidying up. (#7925) 1674fe96ff5 InputText: amends: add stb_textedit_text() api. (#7925) d1b78179592 InputText: amends: renames, coding style. (#7925) abd07f6d307 InputText: added native support for UTF-8 text editing and god rid of the wchar buffer. (#7925) 67cd4ead650 Added io.ConfigDebugHighlightIdConflicts debug feature! (#7961, #7669) a8eec244056 Demo: fix some id conflicts. (#7961) 4236bc088fd Backends: SDL2: use SDL_Vulkan_GetDrawableSize with Vulkan instead of SDL_GL_GetDrawableSize. (#7967, #3190) 15cb7d61f98 InputText: moved imstb_textedit.h include to imgui_widgets.cpp ca5701d4580 InputText: moved all ImGuiInputTextState functions to not be inline. 21d03edcb0c InputText: renamed namespace from stb_texture structure and added an indirection. a2366f90224 TextLinkOpenURL: display a verb in front the link. Update Gallery & other links. (#7885, #7660) a5cf4fe374d InputText: added CJK double-width punctuation to list of separators considered for CTRL+Arrow. d16cb171c66 Nav: pressing any keyboard key while holding Alt disable toggling nav layer on Alt release. (#4439, extend #370, #369) 193c1e23668 Version 1.91.2 WIP d0b742efdee CI: build with Clang C++26 on Linux. (#7954) 4a1a38f7ed0 CI: Amend 943fd21. 943fd216eca CI: Amend e3cb016. e3cb0163284 CI: upgrade Ubuntu version to get newer Clang. Add C++26 build test. (#7954) 41eebc87a06 Fixed C++26 invalid enum operation (#7954) 1dfbb100d6c Version 1.91.1 f75cf62d2f3 Tables: fixed resizing columns when using multiple synched instances that are layed out at different X positions. (#7933) 8dd33839f02 Tables: fixed an issue detecting hovering column/row when using multiple synched instances layed out at different X positions. (#7933) 722a2a12fb2 Tables: comments. (#7937) 776813416b5 PlotHistogram, PlotLines: use ButtonBehavior() to be idiomatic. (#7935, #3072) afb15e97958 PlotHistogram, PlotLines: register item ID in a more idiomatic manner. (#7935, #3072) f99febfd6fa Made BeginItemTooltip() and IsItemHovered() with delay flag infer an implicit ID using Pos only. (#7945, #1485, #143) a93f7db875c Misc merge/small stuff from docking to reduce drift. 30dcdcbe736 Backends: GLFW: Emscripten: use OpenURL() when available and using EMSCRIPTEN_USE_PORT_CONTRIB_GLFW3. Fixes popup blocked in some browsers. (#7915, #7660) 07be01767af Demo: added emscripten version. (#7915) 4832027eb6a Examples: SDL3: Update for API changes: SDL_Init() returns 0 on failure. 6a7319543c4 Backends: SDL3: following SDL3 reverting their change, result of SDL_GetGamepads must be freed. (#7918, #7898, #7807) ee9e3a2ed66 Tabs: avoid queuing a refocus when tab is already focused, which would have the side-effect of e.g. closing popup on a mouse release. (#7914) 4a06fe59b4d Update FONTS.md (#7944) 28caa223567 Fix minor typo (#7943) 1d88609043f Changed call from cosf to ImCos (#7939) 864a2bf6b82 Tables: another attempt at making contents not overlap the bottom and right border in a scrolling table. (#6765, #3752, #7428) a131c3e6111 Tables: revert a34071876 extending outer bottom/right border by 1, this is not the right solution. (#6765, #3752) 0b9adc2c799 BeginChild: (BREAKING) renamed ImGuiChildFlags_Border to ImGuiChildFlags_Borders. 1e939fcc32a Tooltips, Drag and Drop: made it possible to override BeginTooltip() position while inside a drag and drop source or target. (#6973) 088e6fc0471 Examples: Win32+OpenGL3: added batch. file for msys2/mingw build. (#6544) 438f9e1a3e7 InputText: amend d474ed7 for static analysis. (#7913) ce484301c0f CI: Add manual trigger for 'workflow_run' builds (#7865) d474ed7f78c InputText: Internals: store Scroll.y as it seems sane to (internally) expose it in a way that's agnostic of our use of a child window (#7913, #383) d15da2c47d9 Backends: GLFW: undo accidentally not committing use of Platform_SetClipboardTextFn as I was testing the legacy path (amend 214977e). 5de7f69cbb9 (BREAKING) Commented out obsolete ImageButton(). (#5533, #4471, #2464, #1390) 214977e5fd1 IO: (BREAKING) moved io.GetClipboardTextFn, io.SetClipboardTextFn to platform_io.Platform_GetClipboardTextFn, platform_io.Platform_SetClipboardTextFn. e54f240ea0a IO: (BREAKING) moved io.PlatformLocaleDecimalPoint to platform_io.Platform_LocaleDecimalPoint. (#7389, #6719, #2278) 9ff60ae31d5 IO: (BREAKING) moved GetIO().PlatformSetImeDataFn to GetPlatformIO(.Platform_SetImeDataFn. (#7660) ba2f4a2cd56 IO: (BREAKING) moved GetIO().PlatformOpenInShellFn to GetPlatformIO(.Platform_OpenInShellFn. (#7660) e6460722ea1 IO: Added GetPlatformIO(), ImGuiPlatformIO, currently empty. 8e401047952 Backends: GLFW: passing null window to glfwGetClipboardString()/glfwSetClipboardString(). bf75504d7a4 Style: added PushStyleVarX(), PushStyleVarY() helpers to modify only one component of a ImVec2 var. 521f84a3a9f InputText: fixed an issue programmatically refocusing a multi-line input which was just active. (#4761, #7870) 8a946b69e98 InputText: allow callback to update buffer while in read-only mode (fix for imgui_memory_editor 0.54 in read-only mode). 59e69dc6df7 ImGuiSelectionBasicStorage constructor needs visibility (#7906) e471206b088 Windows: adjust default ClipRect to better match rendering of thick borders. (#7887, #7888 + #3312, #7540, #3756, #6170, #6365) eb7201b9026 Fonts: Made it possible to use PushFont()/PopFont() calls accross Begin() calls. (#3224, #3875, #6398, #7903) ecb1962013d IO, InputText: missing changelog entry (amend 092c88d) + readme note on missing features. 092c88dc7bd IO: rework interleaved keys<>char trickling: only trickle for keys known to be likely to input characters. (#7889, #4921, #4858) fabceaf0369 Internals: renamed IsModKey() -> IsLRModKey() and GetModForModKey() -> GetModForLRModKey() to be more explicit. 61313a75891 Docs: better promote IMGUI_DEFINE_MATH_OPERATORS. (#6164, #6137, #5966, #2832) 2d99052d1d4 Backends: SDL2, SDL3: storing SDL_WindowID inside ImGuiViewport::PlatformHandle instead of SDL_Window*. (#7853) 1b61d55079a Backends: SDL2, SDL3: ignore events of other SDL windows, amends + wrapping into a function as it'll be convenient for multi-viewport check. (#7853) 591a18a9c4b Backends: SDL2, SDL3: ignore events of other SDL windows. (#7853) 29fadad1939 TextLink(), TextLinkOpenURL(): change mouse cursor to Hand shape when hovered. (#7885, #7660) 45e7f7827a5 Examples: SDL2+SDLRenderer: fixed return value. (#7876) 3232070d3ab Demo: Fixed truncation warning. (#7857) 4b654db9040 CI: Build example_sdl2_sdlrenderer2 with msbuild (#7864) 8cc6eee2958 Fonts: amend assert when glyph range data seems incorrect. (#7856) 6864a7f839c Window refresh policy: extend tests to any window in the begin stack. (#7797) 531364d7289 Window refresh policy: fixed child window of skiprefresh windows not displaying. (#7797) 9f8f5e11455 MultiSelect+TreeNode: default open behavior is OpenOnDoubleClick + OpenOnArrow when used in a multi-select context without any OpenOnXXX flags set. (#7850) 2981a10c537 MultiSelect, TreeNode, Drag and Drop: fixed an issue where carrying a drag and drop payload over an already open tree node would select it. (#7850) 5e7dc72c926 Examples: SDL3: Update readme to use SDL3_DIR (#7846) fd57b252ac1 Examples: Fix for Emscripten. GLFW+WGPU: rework examples main loop to handle minimization. (#7844) 71ee2ce3673 Examples: GLFW: rework examples main loop to handle minimization without burning CPU or GPU by running unthrottled code. (#7844) 887478793b8 Examples: SDL2 (all), SDL3 (all), Win32+OpenGL3: Rework examples main loop to handle minimization without burning CPU or GPU by running unthrottled code. (#7844) dcf54782d4b Version 1.91.WIP git-subtree-dir: external/imgui/imgui git-subtree-split: cb16568fca5297512ff6a8f3b877f461c4323fbe
503 lines
24 KiB
Markdown
503 lines
24 KiB
Markdown
_(You may browse this at https://github.com/ocornut/imgui/blob/master/docs/FONTS.md or view this file with any Markdown viewer)_
|
|
|
|
## Dear ImGui: Using Fonts
|
|
|
|
The code in imgui.cpp embeds a copy of 'ProggyClean.ttf' (by Tristan Grimmer),
|
|
a 13 pixels high, pixel-perfect font used by default. We embed it in the source code so you can use Dear ImGui without any file system access. ProggyClean does not scale smoothly, therefore it is recommended that you load your own file when using Dear ImGui in an application aiming to look nice and wanting to support multiple resolutions.
|
|
|
|
You may also load external .TTF/.OTF files.
|
|
In the [misc/fonts/](https://github.com/ocornut/imgui/tree/master/misc/fonts) folder you can find a few suggested fonts, provided as a convenience.
|
|
|
|
**Also read the FAQ:** https://www.dearimgui.com/faq (there is a Fonts section!)
|
|
|
|
## Index
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [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)
|
|
- [Loading Font Data Embedded In Source Code](#loading-font-data-embedded-in-source-code)
|
|
- [Using Icon Fonts](#using-icon-fonts)
|
|
- [Using FreeType Rasterizer (imgui_freetype)](#using-freetype-rasterizer-imgui_freetype)
|
|
- [Using Colorful Glyphs/Emojis](#using-colorful-glyphsemojis)
|
|
- [Using Custom Glyph Ranges](#using-custom-glyph-ranges)
|
|
- [Using Custom Colorful Icons](#using-custom-colorful-icons)
|
|
- [About Filenames](#about-filenames)
|
|
- [About UTF-8 Encoding](#about-utf-8-encoding)
|
|
- [Debug Tools](#debug-tools)
|
|
- [Credits/Licenses For Fonts Included In Repository](#creditslicenses-for-fonts-included-in-repository)
|
|
- [Font Links](#font-links)
|
|
|
|
---------------------------------------
|
|
|
|
## Troubleshooting
|
|
|
|
**A vast majority of font and text related issues encountered comes from 4 things:**
|
|
|
|
### (1) Invalid filename due to use of `\` or unexpected working directory.
|
|
|
|
See [About Filenames](#about-filenames). AddFontXXX functions should assert if the filename is incorrect.
|
|
|
|
### (2) Invalid UTF-8 encoding of your non-ASCII strings.
|
|
|
|
See [About UTF-8 Encoding](#about-utf-8-encoding). Use the encoding viewer to confirm encoding of string literal in your source code is correct.
|
|
|
|
### (3) Missing glyph ranges.
|
|
|
|
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.
|
|
All loaded fonts glyphs are rendered into a single texture atlas ahead of time. Calling either of `io.Fonts->GetTexDataAsAlpha8()`, `io.Fonts->GetTexDataAsRGBA32()` or `io.Fonts->Build()` will build the atlas. This is generally called by the Renderer backend, e.g. `ImGui_ImplDX11_NewFrame()` calls it. **If you use custom glyphs ranges, make sure the array is persistent** and available during the calls to `GetTexDataAsAlpha8()/GetTexDataAsRGBA32()/Build()`.
|
|
|
|
### (4) Font atlas texture fails to upload to GPU.
|
|
|
|
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)
|
|
|
|
Some solutions:
|
|
- You may reduce oversampling, e.g. `font_config.OversampleH = 1`, this will half your texture size for a quality loss.
|
|
Note that while OversampleH = 2 looks visibly very close to 3 in most situations, with OversampleH = 1 the quality drop will be noticeable. Read about oversampling [here](https://github.com/nothings/stb/blob/master/tests/oversample).
|
|
- Reduce glyphs ranges by calculating them from source localization data.
|
|
You can use the `ImFontGlyphRangesBuilder` for this purpose and rebuilding your atlas between frames when new characters are needed. This will be the biggest win!
|
|
- Set `io.Fonts.Flags |= ImFontAtlasFlags_NoPowerOfTwoHeight;` to disable rounding the texture height to the next power of two.
|
|
- Set `io.Fonts.TexDesiredWidth` to specify a texture width to reduce maximum texture height (see comment in `ImFontAtlas::Build()` function).
|
|
|
|
Future versions of Dear ImGui should solve this problem.
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## How should I handle DPI in my application?
|
|
|
|
See [FAQ entry](https://github.com/ocornut/imgui/blob/master/docs/FAQ.md#q-how-should-i-handle-dpi-in-my-application).
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Fonts Loading Instructions
|
|
|
|
**Load default font:**
|
|
```cpp
|
|
ImGuiIO& io = ImGui::GetIO();
|
|
io.Fonts->AddFontDefault();
|
|
```
|
|
|
|
**Load .TTF/.OTF file with:**
|
|
```cpp
|
|
ImGuiIO& io = ImGui::GetIO();
|
|
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
|
|
```
|
|
If you get an assert stating "Could not load font file!", your font filename is likely incorrect. Read [About filenames](#about-filenames) carefully.
|
|
|
|
**Load multiple fonts:**
|
|
```cpp
|
|
// Init
|
|
ImGuiIO& io = ImGui::GetIO();
|
|
ImFont* font1 = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
|
|
ImFont* font2 = io.Fonts->AddFontFromFileTTF("anotherfont.otf", size_pixels);
|
|
```
|
|
|
|
In your application loop, select which font to use:
|
|
```cpp
|
|
ImGui::Text("Hello"); // use the default font (which is the first loaded font)
|
|
ImGui::PushFont(font2);
|
|
ImGui::Text("Hello with another font");
|
|
ImGui::PopFont();
|
|
```
|
|
|
|
**For advanced options create a ImFontConfig structure and pass it to the AddFont() function (it will be copied internally):**
|
|
```cpp
|
|
ImFontConfig config;
|
|
config.OversampleH = 2;
|
|
config.OversampleV = 1;
|
|
config.GlyphExtraSpacing.x = 1.0f;
|
|
ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, &config);
|
|
```
|
|
|
|
**Combine multiple fonts into one:**
|
|
```cpp
|
|
// Load a first font
|
|
ImFont* font = io.Fonts->AddFontDefault();
|
|
|
|
// Add character ranges and merge into the previous font
|
|
// The ranges array is not copied by the AddFont* functions and is used lazily
|
|
// so ensure it is available at the time of building or calling GetTexDataAsRGBA32().
|
|
static const ImWchar icons_ranges[] = { 0xf000, 0xf3ff, 0 }; // Will not be copied by AddFont* so keep in scope.
|
|
ImFontConfig config;
|
|
config.MergeMode = true;
|
|
io.Fonts->AddFontFromFileTTF("DroidSans.ttf", 18.0f, &config, io.Fonts->GetGlyphRangesJapanese()); // Merge into first font
|
|
io.Fonts->AddFontFromFileTTF("fontawesome-webfont.ttf", 18.0f, &config, icons_ranges); // Merge into first font
|
|
io.Fonts->Build();
|
|
```
|
|
|
|
**Add a fourth parameter to bake specific font ranges only:**
|
|
|
|
```cpp
|
|
// Basic Latin, Extended Latin
|
|
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, nullptr, io.Fonts->GetGlyphRangesDefault());
|
|
|
|
// Default + Selection of 2500 Ideographs used by Simplified Chinese
|
|
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, nullptr, io.Fonts->GetGlyphRangesChineseSimplifiedCommon());
|
|
|
|
// Default + Hiragana, Katakana, Half-Width, Selection of 1946 Ideographs
|
|
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, nullptr, io.Fonts->GetGlyphRangesJapanese());
|
|
```
|
|
See [Using Custom Glyph Ranges](#using-custom-glyph-ranges) section to create your own ranges.
|
|
|
|
**Example loading and using a Japanese font:**
|
|
|
|
```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"ロード"))
|
|
{
|
|
// do stuff
|
|
}
|
|
ImGui::InputText("string", buf, IM_ARRAYSIZE(buf));
|
|
ImGui::SliderFloat("float", &f, 0.0f, 1.0f);
|
|
```
|
|
|
|
![sample code output](https://raw.githubusercontent.com/wiki/ocornut/imgui/web/v160/code_sample_02_jp.png)
|
|
<br>_(settings: Dark style (left), Light style (right) / Font: NotoSansCJKjp-Medium, 20px / Rounding: 5)_
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Loading Font Data from Memory
|
|
|
|
```cpp
|
|
ImFont* font = io.Fonts->AddFontFromMemoryTTF(data, data_size, size_pixels, ...);
|
|
```
|
|
|
|
IMPORTANT: `AddFontFromMemoryTTF()` by default transfer ownership of the data buffer to the font atlas, which will attempt to free it on destruction.
|
|
This was to avoid an unnecessary copy, and is perhaps not a good API (a future version will redesign it).
|
|
If you want to keep ownership of the data and free it yourself, you need to clear the `FontDataOwnedByAtlas` field:
|
|
|
|
```cpp
|
|
ImFontConfig font_cfg;
|
|
font_cfg.FontDataOwnedByAtlas = false;
|
|
ImFont* font = io.Fonts->AddFontFromMemoryTTF(data, data_size, size_pixels, &font_cfg);
|
|
```
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Loading Font Data Embedded In Source Code
|
|
|
|
- Compile and use [binary_to_compressed_c.cpp](https://github.com/ocornut/imgui/blob/master/misc/fonts/binary_to_compressed_c.cpp) to create a compressed C style array that you can embed in source code.
|
|
- See the documentation in [binary_to_compressed_c.cpp](https://github.com/ocornut/imgui/blob/master/misc/fonts/binary_to_compressed_c.cpp) for instructions on how to use the tool.
|
|
- You may find a precompiled version binary_to_compressed_c.exe for Windows inside the demo binaries package (see [README](https://github.com/ocornut/imgui/blob/master/docs/README.md)).
|
|
- The tool can optionally output Base85 encoding to reduce the size of _source code_ but the read-only arrays in the actual binary will be about 20% bigger.
|
|
|
|
Then load the font with:
|
|
```cpp
|
|
ImFont* font = io.Fonts->AddFontFromMemoryCompressedTTF(compressed_data, compressed_data_size, size_pixels, ...);
|
|
```
|
|
or
|
|
```cpp
|
|
ImFont* font = io.Fonts->AddFontFromMemoryCompressedBase85TTF(compressed_data_base85, size_pixels, ...);
|
|
```
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Using Icon Fonts
|
|
|
|
Using an icon font (such as [FontAwesome](http://fontawesome.io) or [OpenFontIcons](https://github.com/traverseda/OpenFontIcons)) is an easy and practical way to use icons in your Dear ImGui application.
|
|
A common pattern is to merge the icon font within your main font, so you can embed icons directly from your strings without having to change fonts back and forth.
|
|
|
|
To refer to the icon UTF-8 codepoints from your C++ code, you may use those headers files created by Juliette Foucaut: https://github.com/juliettef/IconFontCppHeaders.
|
|
|
|
So you can use `ICON_FA_SEARCH` as a string that will render as a "Search" icon.
|
|
|
|
Example Setup:
|
|
```cpp
|
|
// Merge icons into default tool font
|
|
#include "IconsFontAwesome.h"
|
|
ImGuiIO& io = ImGui::GetIO();
|
|
io.Fonts->AddFontDefault();
|
|
|
|
ImFontConfig config;
|
|
config.MergeMode = true;
|
|
config.GlyphMinAdvanceX = 13.0f; // Use if you want to make the icon monospaced
|
|
static const ImWchar icon_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };
|
|
io.Fonts->AddFontFromFileTTF("fonts/fontawesome-webfont.ttf", 13.0f, &config, icon_ranges);
|
|
```
|
|
Example Usage:
|
|
```cpp
|
|
// Usage, e.g.
|
|
ImGui::Text("%s among %d items", ICON_FA_SEARCH, count);
|
|
ImGui::Button(ICON_FA_SEARCH " Search");
|
|
// C string _literals_ can be concatenated at compilation time, e.g. "hello" " world"
|
|
// ICON_FA_SEARCH is defined as a string literal so this is the same as "A" "B" becoming "AB"
|
|
```
|
|
See Links below for other icons fonts and related tools.
|
|
|
|
**Monospace Icons?**
|
|
|
|
To make your icon look more monospace and facilitate alignment, you may want to set the ImFontConfig::GlyphMinAdvanceX value when loading an icon font.
|
|
|
|
**Screenshot**
|
|
|
|
Here's an application using icons ("Avoyd", https://www.avoyd.com):
|
|
![avoyd](https://user-images.githubusercontent.com/8225057/81696852-c15d9e80-9464-11ea-9cab-2a4d4fc84396.jpg)
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Using FreeType Rasterizer (imgui_freetype)
|
|
|
|
- Dear ImGui uses imstb\_truetype.h to rasterize fonts (with optional oversampling). This technique and its implementation are not ideal for fonts rendered at small sizes, which may appear a little blurry or hard to read.
|
|
- There is an implementation of the ImFontAtlas builder using FreeType that you can use in the [misc/freetype/](https://github.com/ocornut/imgui/tree/master/misc/freetype) folder.
|
|
- FreeType supports auto-hinting which tends to improve the readability of small fonts.
|
|
- Read documentation in the [misc/freetype/](https://github.com/ocornut/imgui/tree/master/misc/freetype) folder.
|
|
- Correct sRGB space blending will have an important effect on your font rendering quality.
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Using Colorful Glyphs/Emojis
|
|
|
|
- Rendering of colored emojis is supported by imgui_freetype with FreeType 2.10+.
|
|
- You will need to load fonts with the `ImGuiFreeTypeBuilderFlags_LoadColor` flag.
|
|
- Emojis are frequently encoded in upper Unicode layers (character codes >0x10000) and will need dear imgui compiled with `IMGUI_USE_WCHAR32`.
|
|
- Not all types of color fonts are supported by FreeType at the moment.
|
|
- Stateful Unicode features such as skin tone modifiers are not supported by the text renderer.
|
|
|
|
![colored glyphs](https://user-images.githubusercontent.com/8225057/106171241-9dc4ba80-6191-11eb-8a69-ca1467b206d1.png)
|
|
|
|
```cpp
|
|
io.Fonts->AddFontFromFileTTF("../../../imgui_dev/data/fonts/NotoSans-Regular.ttf", 16.0f);
|
|
static ImWchar ranges[] = { 0x1, 0x1FFFF, 0 };
|
|
static ImFontConfig cfg;
|
|
cfg.OversampleH = cfg.OversampleV = 1;
|
|
cfg.MergeMode = true;
|
|
cfg.FontBuilderFlags |= ImGuiFreeTypeBuilderFlags_LoadColor;
|
|
io.Fonts->AddFontFromFileTTF("C:\\Windows\\Fonts\\seguiemj.ttf", 16.0f, &cfg, ranges);
|
|
```
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Using Custom Glyph Ranges
|
|
|
|
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<ImWchar> ranges;
|
|
ImFontGlyphRangesBuilder builder;
|
|
builder.AddText("Hello world"); // Add a string (here "Hello world" contains 7 unique characters)
|
|
builder.AddChar(0x7262); // Add a specific character
|
|
builder.AddRanges(io.Fonts->GetGlyphRangesJapanese()); // Add one of the default ranges
|
|
builder.BuildRanges(&ranges); // Build the final result (ordered ranges with all the unique characters submitted)
|
|
|
|
io.Fonts->AddFontFromFileTTF("myfontfile.ttf", size_in_pixels, nullptr, ranges.Data);
|
|
io.Fonts->Build(); // Build the atlas while 'ranges' is still in scope and not deleted.
|
|
```
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Using Custom Colorful Icons
|
|
|
|
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()`.
|
|
- You can then use `ImFontAtlas::GetCustomRectByIndex(int)` to query the position/size of your rectangle within the texture, and blit/copy any graphics data of your choice into those rectangles.
|
|
- This API is beta because it is likely to change in order to support multi-dpi (multiple viewports on multiple monitors with varying DPI scale).
|
|
|
|
#### Pseudo-code:
|
|
```cpp
|
|
// Add font, then register two custom 13x13 rectangles mapped to glyph 'a' and 'b' of this font
|
|
ImFont* font = io.Fonts->AddFontDefault();
|
|
int rect_ids[2];
|
|
rect_ids[0] = io.Fonts->AddCustomRectFontGlyph(font, 'a', 13, 13, 13+1);
|
|
rect_ids[1] = io.Fonts->AddCustomRectFontGlyph(font, 'b', 13, 13, 13+1);
|
|
|
|
// Build atlas
|
|
io.Fonts->Build();
|
|
|
|
// Retrieve texture in RGBA format
|
|
unsigned char* tex_pixels = nullptr;
|
|
int tex_width, tex_height;
|
|
io.Fonts->GetTexDataAsRGBA32(&tex_pixels, &tex_width, &tex_height);
|
|
|
|
for (int rect_n = 0; rect_n < IM_ARRAYSIZE(rect_ids); rect_n++)
|
|
{
|
|
int rect_id = rect_ids[rect_n];
|
|
if (const ImFontAtlasCustomRect* rect = io.Fonts->GetCustomRectByIndex(rect_id))
|
|
{
|
|
// Fill the custom rectangle with red pixels (in reality you would draw/copy your bitmap data here!)
|
|
for (int y = 0; y < rect->Height; y++)
|
|
{
|
|
ImU32* p = (ImU32*)tex_pixels + (rect->Y + y) * tex_width + (rect->X);
|
|
for (int x = rect->Width; x > 0; x--)
|
|
*p++ = IM_COL32(255, 0, 0, 255);
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## About Filenames
|
|
|
|
**Please note that many new C/C++ users have issues loading their files _because the filename they provide is wrong_ due to incorrect assumption of what is the current directory.**
|
|
|
|
Two things to watch for:
|
|
|
|
(1) In C/C++ and most programming languages if you want to use a backslash `\` within a string literal, you need to write it double backslash `\\`. At it happens, Windows uses backslashes as a path separator, so be mindful.
|
|
```cpp
|
|
io.Fonts->AddFontFromFileTTF("MyFiles\MyImage01.jpg", ...); // This is INCORRECT!!
|
|
io.Fonts->AddFontFromFileTTF("MyFiles\\MyImage01.jpg", ...); // This is CORRECT
|
|
```
|
|
In some situations, you may also use `/` path separator under Windows.
|
|
|
|
(2) Make sure your IDE/debugger settings starts your executable from the right working (current) directory. In Visual Studio you can change your working directory in project `Properties > General > Debugging > Working Directory`. People assume that their execution will start from the root folder of the project, where by default it often starts from the folder where object or executable files are stored.
|
|
```cpp
|
|
io.Fonts->AddFontFromFileTTF("MyImage01.jpg", ...); // Relative filename depends on your Working Directory when running your program!
|
|
io.Fonts->AddFontFromFileTTF("../MyImage01.jpg", ...); // Load from the parent folder of your Working Directory
|
|
```
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## About UTF-8 Encoding
|
|
|
|
**For non-ASCII characters display, a common user issue is not passing correctly UTF-8 encoded strings.**
|
|
|
|
(1) We provide a function `ImGui::DebugTextEncoding(const char* text)` which you can call to verify the content of your UTF-8 strings.
|
|
This is a convenient way to confirm that your encoding is correct.
|
|
|
|
```cpp
|
|
ImGui::SeparatorText("CORRECT");
|
|
ImGui::DebugTextEncoding(u8"こんにちは");
|
|
|
|
ImGui::SeparatorText("INCORRECT");
|
|
ImGui::DebugTextEncoding("こんにちは");
|
|
```
|
|
![UTF-8 Encoding viewer](https://github.com/ocornut/imgui/assets/8225057/61c1696a-9a94-46c5-9627-cf91211111f0)
|
|
|
|
You can also find this tool under `Metrics/Debuggers->Tools->UTF-8 Encoding viewer` if you want to paste from clipboard, but this won't validate the UTF-8 encoding done by your compiler.
|
|
|
|
(2) To encode in UTF-8:
|
|
|
|
There are also compiler-specific ways to enforce UTF-8 encoding by default:
|
|
|
|
- Visual Studio compiler: `/utf-8` command-line flag.
|
|
- Visual Studio compiler: `#pragma execution_character_set("utf-8")` inside your code.
|
|
- Since May 2023 we have changed the Visual Studio projects of all our examples to use `/utf-8` ([see commit](https://github.com/ocornut/imgui/commit/513af1efc9080857bbd10000d98f98f2a0c96803)).
|
|
|
|
Or, since C++11, you can use the `u8"my text"` syntax to encode literal strings as UTF-8. e.g.:
|
|
```cpp
|
|
ImGui::Text(u8"hello");
|
|
ImGui::Text(u8"こんにちは"); // this will always be encoded as UTF-8
|
|
ImGui::Text("こんにちは"); // the encoding of this is depending on compiler settings/flags and may be incorrect.
|
|
```
|
|
|
|
Since C++20, because the C++ committee hate its users, they decided to change the `u8""` syntax to not return `const char*` but a new type `const char8_t*` which doesn't cast to `const char*`.
|
|
Because of type usage of `u8""` in C++20 is a little more tedious:
|
|
```cpp
|
|
ImGui::Text((const char*)u8"こんにちは");
|
|
```
|
|
However, you can disable this behavior completely using the compiler option [`/Zc:char8_t-`](https://learn.microsoft.com/en-us/cpp/build/reference/zc-char8-t?view=msvc-170) for MSVC and [`-fno-char8_t`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1423r3.html) for Clang and GCC.
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Debug Tools
|
|
|
|
#### Metrics/Debugger->Fonts
|
|
You can use the `Metrics/Debugger` window (available in `Demo>Tools`) to browse your fonts and understand what's going on if you have an issue. You can also reach it in `Demo->Tools->Style Editor->Fonts`. The same information are also available in the Style Editor under Fonts.
|
|
|
|
![Fonts debugging](https://user-images.githubusercontent.com/8225057/135429892-0e41ef8d-33c5-4991-bcf6-f997a0bcfd6b.png)
|
|
|
|
#### UTF-8 Encoding Viewer**
|
|
You can use the `UTF-8 Encoding viewer` in `Metrics/Debugger` to verify the content of your UTF-8 strings. From C/C++ code, you can call `ImGui::DebugTextEncoding("my string");` function to verify that your UTF-8 encoding is correct.
|
|
|
|
![UTF-8 Encoding viewer](https://user-images.githubusercontent.com/8225057/166505963-8a0d7899-8ee8-4558-abb2-1ae523dc02f9.png)
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
---------------------------------------
|
|
|
|
## Credits/Licenses For Fonts Included In Repository
|
|
|
|
Some fonts files are available in the `misc/fonts/` folder:
|
|
|
|
**Roboto-Medium.ttf**, by Christian Robetson
|
|
<br>Apache License 2.0
|
|
<br>https://fonts.google.com/specimen/Roboto
|
|
|
|
**Cousine-Regular.ttf**, by Steve Matteson
|
|
<br>Digitized data copyright (c) 2010 Google Corporation.
|
|
<br>Licensed under the SIL Open Font License, Version 1.1
|
|
<br>https://fonts.google.com/specimen/Cousine
|
|
|
|
**DroidSans.ttf**, by Steve Matteson
|
|
<br>Apache License 2.0
|
|
<br>https://www.fontsquirrel.com/fonts/droid-sans
|
|
|
|
**ProggyClean.ttf**, by Tristan Grimmer
|
|
<br>MIT License
|
|
<br>(recommended loading setting: Size = 13.0, GlyphOffset.y = +1)
|
|
<br>http://www.proggyfonts.net/
|
|
|
|
**ProggyTiny.ttf**, by Tristan Grimmer
|
|
<br>MIT License
|
|
<br>(recommended loading setting: Size = 10.0, GlyphOffset.y = +1)
|
|
<br>http://www.proggyfonts.net/
|
|
|
|
**Karla-Regular.ttf**, by Jonathan Pinhorn
|
|
<br>SIL OPEN FONT LICENSE Version 1.1
|
|
|
|
##### [Return to Index](#index)
|
|
|
|
## Font Links
|
|
|
|
#### ICON FONTS
|
|
|
|
- C/C++ header for icon fonts (#define with code points to use in source code string literals) https://github.com/juliettef/IconFontCppHeaders
|
|
- FontAwesome https://fortawesome.github.io/Font-Awesome
|
|
- OpenFontIcons https://github.com/traverseda/OpenFontIcons
|
|
- Google Icon Fonts https://design.google.com/icons/
|
|
- Kenney Icon Font (Game Controller Icons) https://github.com/nicodinh/kenney-icon-font
|
|
- IcoMoon - Custom Icon font builder https://icomoon.io/app
|
|
|
|
#### REGULAR FONTS
|
|
|
|
- Google Noto Fonts (worldwide languages) https://www.google.com/get/noto/
|
|
- Open Sans Fonts https://fonts.google.com/specimen/Open+Sans
|
|
- (Japanese) M+ fonts by Coji Morishita http://mplus-fonts.sourceforge.jp/mplus-outline-fonts/index-en.html
|
|
|
|
#### MONOSPACE FONTS
|
|
|
|
Pixel Perfect:
|
|
- Proggy Fonts, by Tristan Grimmer http://www.proggyfonts.net or http://upperboundsinteractive.com/fonts.php
|
|
- Sweet16, Sweet16 Mono, by Martin Sedlak (Latin + Supplemental + Extended A) https://github.com/kmar/Sweet16Font (also include an .inl file to use directly in dear imgui.)
|
|
|
|
Regular:
|
|
- Google Noto Mono Fonts https://www.google.com/get/noto/
|
|
- Typefaces for source code beautification https://github.com/chrissimpkins/codeface
|
|
- Programmation fonts http://s9w.github.io/font_compare/
|
|
- Inconsolata http://www.levien.com/type/myfonts/inconsolata.html
|
|
- Adobe Source Code Pro: Monospaced font family for ui & coding environments https://github.com/adobe-fonts/source-code-pro
|
|
- Monospace/Fixed Width Programmer's Fonts http://www.lowing.org/fonts/
|
|
|
|
Or use Arial Unicode or other Unicode fonts provided with Windows for full characters coverage (not sure of their licensing).
|
|
|
|
##### [Return to Index](#index)
|