mirrors/imgui
1
0
Fork 0
mirror of https://github.com/ocornut/imgui.git synced 2025-09-06 03:18:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fonts: add comments and examples for GlyphExcludeRanges[].

Browse Source
This commit is contained in:
ocornut
2025-06-24 10:50:30 +02:00
parent 613a6a964c
commit a49ddaac89
4 changed files with 78 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/CHANGELOG.txt
View File

@@ -62,7 +62,7 @@ Breaking changes:
- Fonts: **IMPORTANT**: if your app was solving the OSX/iOS Retina screen specific - Fonts: **IMPORTANT**: if your app was solving the OSX/iOS Retina screen specific
logical vs display scale problem by setting io.DisplayFramebufferScale (e.g. to 2.0f) logical vs display scale problem by setting io.DisplayFramebufferScale (e.g. to 2.0f)
+ setting io.FontGlobalScale (e.g. to 1.0f/2.0f) + loading fonts at scaled sizes (e.g. size X * 2.0f): + setting io.FontGlobalScale (e.g. to 1.0f/2.0f) + loading fonts at scaled sizes (e.g. size X * 2.0f):
This WILL NOT map correctly to the new system! Because font will rasterize as requested size. - This WILL NOT map correctly to the new system! Because font will rasterize as requested size.
- With a legacy backend (< 1.92): - With a legacy backend (< 1.92):
- Instead of setting io.FontGlobalScale = 1.0f/N -> set ImFontCfg::RasterizerDensity = N. - Instead of setting io.FontGlobalScale = 1.0f/N -> set ImFontCfg::RasterizerDensity = N.
- This already worked before, but is now pretty much required. - This already worked before, but is now pretty much required.
@@ -84,6 +84,26 @@ Breaking changes:
- ImFont::FontSize was removed and does not make sense anymore. - ImFont::FontSize was removed and does not make sense anymore.
ImFont::LegacySize is the size passed to AddFont(). ImFont::LegacySize is the size passed to AddFont().
- Renamed/moved 'io.FontGlobalScale' to 'style.FontScaleMain'. - Renamed/moved 'io.FontGlobalScale' to 'style.FontScaleMain'.
- Fonts: **IMPORTANT** on Font Merging:
- When searching for a glyph in multiple merged fonts: font inputs are now scanned in order
for the first font input which the desired glyph. This is technically a different behavior
than before!
- e.g. If you are merging fonts you may have glyphs that you expected to load from
Font Source 2 which exists in Font Source 1. After the update and when using a new backend,
those glyphs may now loaded from Font Source 1!
- You can use `ImFontConfig::GlyphExcludeRanges[]` to specify ranges to ignore in given Input:
// Add Font Source 1 but ignore ICON_MIN_FA..ICON_MAX_FA range
static ImWchar exclude_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };
ImFontConfig cfg1;
cfg1.GlyphExcludeRanges = exclude_ranges;
io.Fonts->AddFontFromFileTTF("segoeui.ttf", 0.0f, &cfg1);
// Add Font Source 2, which expects to use the range above
ImFontConfig cfg2;
cfg2.MergeMode = true;
io.Fonts->AddFontFromFileTTF("FontAwesome4.ttf", 0.0f, &cfg2);
- You can use `Metrics/Debugger->Fonts->Font->Input Glyphs Overlap Detection Tool` to
see list of glyphs available in multiple font sources. This can facilitate understanding
which font input is providing which glyph.
- Textures: - Textures:
- All API functions taking a 'ImTextureID' parameter are now taking a 'ImTextureRef': - All API functions taking a 'ImTextureID' parameter are now taking a 'ImTextureRef':

39
docs/FONTS.md
View File

@@ -18,6 +18,7 @@ In the [misc/fonts/](https://github.com/ocornut/imgui/tree/master/misc/fonts) fo
- [Loading Font Data from Memory](#loading-font-data-from-memory) - [Loading Font Data from Memory](#loading-font-data-from-memory)
- [Loading Font Data Embedded In Source Code](#loading-font-data-embedded-in-source-code) - [Loading Font Data Embedded In Source Code](#loading-font-data-embedded-in-source-code)
- [Using Icon Fonts](#using-icon-fonts) - [Using Icon Fonts](#using-icon-fonts)
- [Excluding Overlapping Ranges](#excluding-overlapping-ranges)
- [Using FreeType Rasterizer (imgui_freetype)](#using-freetype-rasterizer-imgui_freetype) - [Using FreeType Rasterizer (imgui_freetype)](#using-freetype-rasterizer-imgui_freetype)
- [Using Colorful Glyphs/Emojis](#using-colorful-glyphsemojis) - [Using Colorful Glyphs/Emojis](#using-colorful-glyphsemojis)
- [Using Custom Glyph Ranges](#using-custom-glyph-ranges) - [Using Custom Glyph Ranges](#using-custom-glyph-ranges)
@@ -313,6 +314,44 @@ Here's an application using icons ("Avoyd", https://www.avoyd.com):
--------------------------------------- ---------------------------------------
### Excluding Overlapping Ranges
🆕 **Since 1.92, with an up to date backend: glyphs ranges are ignored**: when loading a glyph, input fonts in the merge list are queried in order. The first font which has the glyph loads it.
<BR>‼️ **If you are merging several fonts, you may have undesirable overlapping ranges.** You can use `ImFontConfig::GlyphExcludeRanges[] `to specify ranges to ignore in a given Input.
```cpp
// Add Font Source 1 but ignore ICON_MIN_FA..ICON_MAX_FA range
static ImWchar exclude_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };
ImFontConfig cfg1;
cfg1.GlyphExcludeRanges = exclude_ranges;
io.Fonts->AddFontFromFileTTF("segoeui.ttf", 0.0f, &cfg1);
// Add Font Source 2, which expects to use the range above
ImFontConfig cfg2;
cfg2.MergeMode = true;
io.Fonts->AddFontFromFileTTF("FontAwesome4.ttf", 0.0f, &cfg2);
```
Another (silly) example:
```cpp
// Remove 'A'-'Z' from first font
static ImWchar exclude_ranges[] = { 'A', 'Z', 0 };
ImFontConfig cfg1;
cfg1.GlyphExcludeRanges = exclude_ranges;
io.Fonts->AddFontFromFileTTF("segoeui.ttf", 0.0f, &cfg1);
// Load another font to fill the gaps
ImFontConfig cfg2;
cfg2.MergeMode = true;
io.Fonts->AddFontFromFileTTF("Roboto-Medium.ttf", 0.0f, &cfg2);
```
![image](https://github.com/user-attachments/assets/f3d751d3-1aee-4698-bd9b-f511902f56bb)
You can use `Metrics/Debugger->Fonts->Font->Input Glyphs Overlap Detection Tool` to see list of glyphs available in multiple font sources. This can facilitate understanding which font input is providing which glyph.
##### [Return to Index](#index)
---------------------------------------
## Using FreeType Rasterizer (imgui_freetype) ## Using FreeType Rasterizer (imgui_freetype)
- Dear ImGui uses [stb_truetype.h](https://github.com/nothings/stb/) 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. - Dear ImGui uses [stb_truetype.h](https://github.com/nothings/stb/) 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.

17
imgui.cpp
View File

@@ -474,6 +474,20 @@ CODE
- Before 1.92: ImGui::PushFont() always used font "default" size specified in AddFont() call. - Before 1.92: ImGui::PushFont() always used font "default" size specified in AddFont() call.
- Since 1.92: ImGui::PushFont() preserve the current font size which is a shared value. - Since 1.92: ImGui::PushFont() preserve the current font size which is a shared value.
- To use old behavior: (A) use 'ImGui::PushFont(font, font->LegacySize)' at call site (preferred). (B) Set 'ImFontConfig::Flags |= ImFontFlags_DefaultToLegacySize' in AddFont() call (not desirable as it requires e.g. third-party code to be aware of it). - To use old behavior: (A) use 'ImGui::PushFont(font, font->LegacySize)' at call site (preferred). (B) Set 'ImFontConfig::Flags |= ImFontFlags_DefaultToLegacySize' in AddFont() call (not desirable as it requires e.g. third-party code to be aware of it).
- Fonts: **IMPORTANT** on Font Merging:
- When searching for a glyph in multiple merged fonts: font inputs are now scanned in orderfor the first font input which the desired glyph. This is technically a different behavior than before!
- e.g. If you are merging fonts you may have glyphs that you expected to load from Font Source 2 which exists in Font Source 1. After the update and when using a new backend, those glyphs may now loaded from Font Source 1!
- You can use `ImFontConfig::GlyphExcludeRanges[]` to specify ranges to ignore in given Input:
// Add Font Source 1 but ignore ICON_MIN_FA..ICON_MAX_FA range
static ImWchar exclude_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };
ImFontConfig cfg1;
cfg1.GlyphExcludeRanges = exclude_ranges;
io.Fonts->AddFontFromFileTTF("segoeui.ttf", 0.0f, &cfg1);
// Add Font Source 2, which expects to use the range above
ImFontConfig cfg2;
cfg2.MergeMode = true;
io.Fonts->AddFontFromFileTTF("FontAwesome4.ttf", 0.0f, &cfg2);
- You can use `Metrics/Debugger->Fonts->Font->Input Glyphs Overlap Detection Tool` to see list of glyphs available in multiple font sources. This can facilitate unde
- Fonts: ImFont::FontSize was removed and does not make sense anymore. ImFont::LegacySize is the size passed to AddFont(). - Fonts: ImFont::FontSize was removed and does not make sense anymore. ImFont::LegacySize is the size passed to AddFont().
- Fonts: Renamed/moved 'io.FontGlobalScale' to 'style.FontScaleMain'. - Fonts: Renamed/moved 'io.FontGlobalScale' to 'style.FontScaleMain'.
- Textures: all API functions taking a 'ImTextureID' parameter are now taking a 'ImTextureRef'. Affected functions are: ImGui::Image(), ImGui::ImageWithBg(), ImGui::ImageButton(), ImDrawList::AddImage(), ImDrawList::AddImageQuad(), ImDrawList::AddImageRounded(). - Textures: all API functions taking a 'ImTextureID' parameter are now taking a 'ImTextureRef'. Affected functions are: ImGui::Image(), ImGui::ImageWithBg(), ImGui::ImageButton(), ImDrawList::AddImage(), ImDrawList::AddImageQuad(), ImDrawList::AddImageRounded().
@@ -16958,7 +16972,8 @@ void ImGui::DebugNodeFont(ImFont* font)
} }
if (font->Sources.Size > 1 && TreeNode("Input Glyphs Overlap Detection Tool")) if (font->Sources.Size > 1 && TreeNode("Input Glyphs Overlap Detection Tool"))
{ {
TextWrapped("- First Input that contains the glyph is used.\n- Use ImFontConfig::GlyphExcludeRanges[] to specify ranges to ignore glyph in given Input.\n- This tool doesn't cache results and is slow, don't keep it open!"); TextWrapped("- First Input that contains the glyph is used.\n"
"- Use ImFontConfig::GlyphExcludeRanges[] to specify ranges to ignore glyph in given Input.\n- Prefer using a small number of ranges as the list is scanned every time a new glyph is loaded,\n - e.g. GlyphExcludeRanges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };\n- This tool doesn't cache results and is slow, don't keep it open!");
if (BeginTable("table", 2)) if (BeginTable("table", 2))
{ {
for (unsigned int c = 0; c < 0x10000; c++) for (unsigned int c = 0; c < 0x10000; c++)

2
imgui.h
View File

@@ -3474,7 +3474,7 @@ struct ImFontConfig
ImS8 OversampleV; // 0 (1) // Rasterize at higher quality for sub-pixel positioning. 0 == auto == 1. This is not really useful as we don't use sub-pixel positions on the Y axis. ImS8 OversampleV; // 0 (1) // Rasterize at higher quality for sub-pixel positioning. 0 == auto == 1. This is not really useful as we don't use sub-pixel positions on the Y axis.
float SizePixels; // // Size in pixels for rasterizer (more or less maps to the resulting font height). float SizePixels; // // Size in pixels for rasterizer (more or less maps to the resulting font height).
const ImWchar* GlyphRanges; // NULL // *LEGACY* THE ARRAY DATA NEEDS TO PERSIST AS LONG AS THE FONT IS ALIVE. Pointer to a user-provided list of Unicode range (2 value per range, values are inclusive, zero-terminated list). const ImWchar* GlyphRanges; // NULL // *LEGACY* THE ARRAY DATA NEEDS TO PERSIST AS LONG AS THE FONT IS ALIVE. Pointer to a user-provided list of Unicode range (2 value per range, values are inclusive, zero-terminated list).
const ImWchar* GlyphExcludeRanges; // NULL // Pointer to a VERY SHORT user-provided list of Unicode range (2 value per range, values are inclusive, zero-terminated list). This is very close to GlyphRanges[] but designed to exclude ranges from a font source, when merging fonts with overlapping glyphs. Use "Input Glyphs Overlap Detection Tool" to find about your overlapping ranges. const ImWchar* GlyphExcludeRanges; // NULL // Pointer to a small user-provided list of Unicode ranges (2 value per range, values are inclusive, zero-terminated list). This is very close to GlyphRanges[] but designed to exclude ranges from a font source, when merging fonts with overlapping glyphs. Use "Input Glyphs Overlap Detection Tool" to find about your overlapping ranges.
//ImVec2 GlyphExtraSpacing; // 0, 0 // (REMOVED AT IT SEEMS LARGELY OBSOLETE. PLEASE REPORT IF YOU WERE USING THIS). Extra spacing (in pixels) between glyphs when rendered: essentially add to glyph->AdvanceX. Only X axis is supported for now. //ImVec2 GlyphExtraSpacing; // 0, 0 // (REMOVED AT IT SEEMS LARGELY OBSOLETE. PLEASE REPORT IF YOU WERE USING THIS). Extra spacing (in pixels) between glyphs when rendered: essentially add to glyph->AdvanceX. Only X axis is supported for now.
ImVec2 GlyphOffset; // 0, 0 // Offset (in pixels) all glyphs from this font input. Absolute value for default size, other sizes will scale this value. ImVec2 GlyphOffset; // 0, 0 // Offset (in pixels) all glyphs from this font input. Absolute value for default size, other sizes will scale this value.
float GlyphMinAdvanceX; // 0 // Minimum AdvanceX for glyphs, set Min to align font icons, set both Min/Max to enforce mono-space font. Absolute value for default size, other sizes will scale this value. float GlyphMinAdvanceX; // 0 // Minimum AdvanceX for glyphs, set Min to align font icons, set both Min/Max to enforce mono-space font. Absolute value for default size, other sizes will scale this value.