(You may browse this document at https://github.com/ocornut/imgui/blob/master/docs/FONTS.md or view this file with any Markdown viewer.)
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 font in source code so you can use Dear ImGui without any file system access.
You may also load external .TTF/.OTF files. In the misc/fonts/
folder you can find a few suggested fonts, provided as a convenience.
Also read the FAQ: https://www.dearimgui.org/faq
Please use the Discord server: http://discord.dearimgui.org and not the Github issue tracker for basic font loading questions.
io.Fonts->GetTexDataAsAlpha8()
, io.Fonts->GetTexDataAsRGBA32()
or io.Fonts->Build()
.ImGui::ShowStyleEditor()
in the “Fonts” section to browse your fonts and understand what's going on if you have an issue.u8"hello" u8"こんにちは" // this will be encoded as UTF-8
\
character in your string literal, you need to double them e.g. "folder\\filename"
.Load default font:
ImGuiIO& io = ImGui::GetIO(); io.Fonts->AddFontDefault();
Load .TTF/.OTF file with:
ImGuiIO& io = ImGui::GetIO(); ImFont* font1 = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels); ImFont* font2 = io.Fonts->AddFontFromFileTTF("anotherfont.otf", size_pixels); // Select font at runtime 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):
ImFontConfig config; config.OversampleH = 2; config.OversampleV = 1; config.GlyphExtraSpacing.x = 1.0f; ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, &config);
Combine two fonts into one:
// 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()); io.Fonts->AddFontFromFileTTF("fontawesome-webfont.ttf", 18.0f, &config, icons_ranges); io.Fonts->Build();
Add a fourth parameter to bake specific font ranges only:
// Basic Latin, Extended Latin io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesDefault()); // Default + Selection of 2500 Ideographs used by Simplified Chinese io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesChineseSimplifiedCommon()); // Default + Hiragana, Katakana, Half-Width, Selection of 1946 Ideographs io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesJapanese());
See Building Custom Glyph Ranges section to create your own ranges. Offset font vertically by altering the io.Font->DisplayOffset value:
ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels); font->DisplayOffset.y = 1; // Render 1 pixel down
Font Atlas too large?
Some solutions:
ImFontGlyphRangesBuilder
for this purpose, this will be the biggest win!font_config.OversampleH = font_config.OversampleV = 1
, this will largely reduce your texture size.io.Fonts.TexDesiredWidth
to specify a texture width to minimize texture height (see comment in ImFontAtlas::Build()
function).io.Fonts.Flags |= ImFontAtlasFlags_NoPowerOfTwoHeight;
to disable rounding the texture height to the next power of two.The C++11 version of those files uses the u8"" UTF-8 encoding syntax:
#define ICON_FA_SEARCH u8"\uf002"
The pre-C++11 version has the values manually encoded as UTF-8:
#define ICON_FA_SEARCH "\xEF\x80\x82"
Example Setup:
// 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:
// 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.
Note
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.
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, NULL, ranges.Data); io.Fonts->Build(); // Build the atlas while 'ranges' is still in scope and not deleted.
(This is a BETA api, use if you are familiar with dear imgui and with your rendering back-end)
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()`.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.// 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 = NULL; 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 = rects_ids[rect_n]; if (const ImFontAtlas::CustomRect* 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); } } }
Then load the font with: ImFont* font = io.Fonts->AddFontFromMemoryCompressedTTF(compressed_data, compressed_data_size, size_pixels, ...);
or ImFont* font = io.Fonts- AddFontFromMemoryCompressedBase85TTF(compressed_data_base85, size_pixels, ...);
Some fonts files are available in the misc/fonts/
folder.
Roboto-Medium.ttf
Apache License 2.0 by Christian Robertson https://fonts.google.com/specimen/Roboto
Cousine-Regular.ttf
by Steve Matteson Digitized data copyright (c) 2010 Google Corporation. Licensed under the SIL Open Font License, Version 1.1 https://fonts.google.com/specimen/Cousine
DroidSans.ttf
Copyright (c) Steve Matteson Apache License, version 2.0 https://www.fontsquirrel.com/fonts/droid-sans
ProggyClean.ttf
Copyright (c) 2004, 2005 Tristan Grimmer MIT License recommended loading setting: Size = 13.0, DisplayOffset.Y = +1 http://www.proggyfonts.net/
ProggyTiny.ttf Copyright (c) 2004, 2005 Tristan Grimmer MIT License recommended loading setting: Size = 10.0, DisplayOffset.Y = +1 http://www.proggyfonts.net/
Karla-Regular.ttf Copyright (c) 2012, Jonathan Pinhorn SIL OPEN FONT LICENSE Version 1.1
Pixel Perfect:
Regular:
Or use Arial Unicode or other Unicode fonts provided with Windows for full characters coverage (not sure of their licensing).