Update FONTS.md
diff --git a/docs/FONTS.md b/docs/FONTS.md index b4ab425..5b8c6c0 100644 --- a/docs/FONTS.md +++ b/docs/FONTS.md
@@ -47,9 +47,10 @@ Load default font: ```cpp - ImGuiIO& io = ImGui::GetIO(); - io.Fonts->AddFontDefault(); +ImGuiIO& io = ImGui::GetIO(); +io.Fonts->AddFontDefault(); ``` + Load .TTF/.OTF file with: ```cpp ImGuiIO& io = ImGui::GetIO(); @@ -62,6 +63,7 @@ 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; @@ -71,7 +73,7 @@ ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, &config); ``` -Combine two fonts into one: +Combine multiple fonts into one: ```cpp // Load a first font ImFont* font = io.Fonts->AddFontDefault(); @@ -82,8 +84,8 @@ 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->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: @@ -123,39 +125,34 @@ --------------------------------------- ## Using Icons -- 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 +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. -**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" ` +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. Those files are full of line such as: + `#define ICON_FA_SEARCH "\xEF\x80\x82"` + +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(); +// 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); +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" +// 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. @@ -163,10 +160,10 @@ ## Using the FreeType Rasterizer - 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/ folder. +- 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. -**Note** +Note: - This code currently creates textures that are unoptimally too large (could be fixed with some work). - Also note that correct sRGB space blending will have an important effect on your font rendering quality. @@ -174,17 +171,17 @@ --------------------------------------- ## Building 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. +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) +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. +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. ``` --------------------------------------- @@ -197,34 +194,34 @@ #### 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); +// 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(); +// 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); +// 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); - } - } - } +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); + } + } +} ``` --------------------------------------- @@ -236,37 +233,38 @@ - 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: - ` ImFont* font = io.Fonts->AddFontFromMemoryCompressedTTF(compressed_data, compressed_data_size, size_pixels, ...);` +```cpp +ImFont* font = io.Fonts->AddFontFromMemoryCompressedTTF(compressed_data, compressed_data_size, size_pixels, ...); +``` or - `ImFont* font = io.Fonts- AddFontFromMemoryCompressedBase85TTF(compressed_data_base85, size_pixels, ...);` +```cpp +ImFont* font = io.Fonts- AddFontFromMemoryCompressedBase85TTF(compressed_data_base85, size_pixels, ...); +``` --------------------------------------- ## Credits/Licenses For Fonts Included In Repository -Some fonts files are available in the `misc/fonts/` folder. +Some fonts files are available in the `misc/fonts/` folder: +``` Roboto-Medium.ttf - Apache License 2.0 - by Christian Robertson + by Christian Robetson 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 @@ -281,7 +279,7 @@ Karla-Regular.ttf Copyright (c) 2012, Jonathan Pinhorn SIL OPEN FONT LICENSE Version 1.1 - +``` --------------------------------------- ## Font Links