github
/
imgui
mirror of https://github.com/ocornut/imgui.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Font readme: Added OpenFontIcons, tweaks, links, removed spaces (#2141)

pull/2150/head
omar 6 years ago
parent
82873c7ad4
commit
e610afeea3
1 changed files with 197 additions and 177 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 374
      misc/fonts/README.txt

374
misc/fonts/README.txt
View File

@ -32,259 +32,279 @@ If you have other loading/merging/adding fonts, you can post on the Dear ImGui "
README FIRST / FAQ README FIRST / FAQ
--------------------------------------- ---------------------------------------
- You can use the style editor ImGui::ShowStyleEditor() to browse your fonts and understand what's going on if you have an issue. - You can use the style editor ImGui::ShowStyleEditor() to browse your fonts and understand what's going on if you have an issue.
- Make sure your font ranges data are persistent (available during the call to GetTexDataAsAlpha8()/GetTexDataAsRGBA32()/Build(). - Make sure your font ranges data are persistent (available during the call to GetTexDataAsAlpha8()/GetTexDataAsRGBA32()/Build().
- Use C++11 u8"my text" syntax to encode literal strings as UTF-8. e.g.: - Use C++11 u8"my text" syntax to encode literal strings as UTF-8. e.g.:
u8"hello" u8"hello"
u8"こんにちは" // this will be encoded as UTF-8 u8"こんにちは" // this will be encoded as UTF-8
- If you want to include a backslash \ character in your string literal, you need to double them e.g. "folder\\filename". - If you want to include a backslash \ character in your string literal, you need to double them e.g. "folder\\filename".
- Please use the Discourse forum (https://discourse.dearimgui.org) and not the Github issue tracker for basic font loading questions. - Please use the Discourse forum (https://discourse.dearimgui.org) and not the Github issue tracker for basic font loading questions.
--------------------------------------- ---------------------------------------
USING ICONS USING ICONS
--------------------------------------- ---------------------------------------
Using an icon font (such as FontAwesome: http://fontawesome.io) is an easy and practical way to use icons in your ImGui application. Using an icon font (such as FontAwesome: http://fontawesome.io or OpenFontIcons. https://github.com/traverseda/OpenFontIcons)
A common pattern is to merge the icon font within your main font, so you can embed icons directly from your strings without is an easy and practical way to use icons in your Dear ImGui application.
having to change fonts back and forth. 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: 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 https://github.com/juliettef/IconFontCppHeaders
The C++11 version of those files uses the u8"" utf-8 encoding syntax + \u The C++11 version of those files uses the u8"" utf-8 encoding syntax + \u
#define ICON_FA_SEARCH u8"\uf002" #define ICON_FA_SEARCH u8"\uf002"
The pre-C++11 version has the values directly encoded as utf-8: The pre-C++11 version has the values directly encoded as utf-8:
#define ICON_FA_SEARCH "\xEF\x80\x82" #define ICON_FA_SEARCH "\xEF\x80\x82"
Example: Example Setup:
// Merge icons into default tool font // Merge icons into default tool font
#include "IconsFontAwesome.h" #include "IconsFontAwesome.h"
ImGuiIO& io = ImGui::GetIO(); ImGuiIO& io = ImGui::GetIO();
io.Fonts->AddFontDefault(); io.Fonts->AddFontDefault();
ImFontConfig config; ImFontConfig config;
config.MergeMode = true; config.MergeMode = true;
config.GlyphMinAdvanceX = 13.0f; // Use if you want to make the icon monospaced 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 }; static const ImWchar icon_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };
io.Fonts->AddFontFromFileTTF("fonts/fontawesome-webfont.ttf", 13.0f, &config, icon_ranges); io.Fonts->AddFontFromFileTTF("fonts/fontawesome-webfont.ttf", 13.0f, &config, icon_ranges);
// Usage, e.g. Example Usage:
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. // Usage, e.g.
ImGui::Text("%s among %d items", ICON_FA_SEARCH, count); 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. See Links below for other icons fonts and related tools.
--------------------------------------- ---------------------------------------
FONTS LOADING INSTRUCTIONS FONTS LOADING INSTRUCTIONS
--------------------------------------- ---------------------------------------
Load default font: Load default font:
ImGuiIO& io = ImGui::GetIO(); ImGuiIO& io = ImGui::GetIO();
io.Fonts->AddFontDefault(); io.Fonts->AddFontDefault();
Load .TTF/.OTF file with: Load .TTF/.OTF file with:
ImGuiIO& io = ImGui::GetIO(); ImGuiIO& io = ImGui::GetIO();
ImFont* font1 = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels); ImFont* font1 = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
ImFont* font2 = io.Fonts->AddFontFromFileTTF("anotherfont.otf", size_pixels); ImFont* font2 = io.Fonts->AddFontFromFileTTF("anotherfont.otf", size_pixels);
// Select font at runtime // Select font at runtime
ImGui::Text("Hello"); // use the default font (which is the first loaded font) ImGui::Text("Hello"); // use the default font (which is the first loaded font)
ImGui::PushFont(font2); ImGui::PushFont(font2);
ImGui::Text("Hello with another font"); ImGui::Text("Hello with another font");
ImGui::PopFont(); ImGui::PopFont();
For advanced options create a ImFontConfig structure and pass it to the AddFont function (it will be copied internally): For advanced options create a ImFontConfig structure and pass it to the AddFont function (it will be copied internally):
ImFontConfig config; ImFontConfig config;
config.OversampleH = 3; config.OversampleH = 3;
config.OversampleV = 1; config.OversampleV = 1;
config.GlyphExtraSpacing.x = 1.0f; config.GlyphExtraSpacing.x = 1.0f;
ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, &config); ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, &config);
If you have very large number of glyphs or multiple fonts, the texture may become too big for your graphics API. If you have very 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 glyphs appears as white rectangles. The typical result of failing to upload a texture is if every glyphs appears as white rectangles.
In particular, using a large range such as GetGlyphRangesChineseSimplifiedCommon() is not recommended unless you In particular, using a large range such as GetGlyphRangesChineseSimplifiedCommon() is not recommended unless you
set OversampleH/OversampleV to 1 and use a small font size. set OversampleH/OversampleV to 1 and use a small font size.
Mind the fact that some graphics drivers have texture size limitation. 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. If you are building a PC application, mind the fact that your users may use hardware with lower limitations than yours.
Some solutions: Some solutions:
- 1) Reduce glyphs ranges by calculating them from source localization data. You can use ImFont::GlyphRangesBuilder for this purpose, - 1) Reduce glyphs ranges by calculating them from source localization data. You can use ImFont::GlyphRangesBuilder for this purpose,
this will be the biggest win. this will be the biggest win.
- 2) You may reduce oversampling, e.g. config.OversampleH = config.OversampleV = 1, this will largely reduce your texture size. - 2) You may reduce oversampling, e.g. config.OversampleH = config.OversampleV = 1, this will largely reduce your texture size.
- 3) Set io.Fonts.TexDesiredWidth to specify a texture width to minimize texture height (see comment in ImFontAtlas::Build function). - 3) Set io.Fonts.TexDesiredWidth to specify a texture width to minimize texture height (see comment in ImFontAtlas::Build function).
- 4) Set io.Fonts.Flags |= ImFontAtlasFlags_NoPowerOfTwoHeight; to disable rounding the texture height to the next power of two. - 4) Set io.Fonts.Flags |= ImFontAtlasFlags_NoPowerOfTwoHeight; to disable rounding the texture height to the next power of two.
Combine two fonts into one: Combine two fonts into one:
// Load a first font // Load a first font
ImFont* font = io.Fonts->AddFontDefault(); ImFont* font = io.Fonts->AddFontDefault();
// Add character ranges and merge into the previous font // Add character ranges and merge into the previous font
// The ranges array is not copied by the AddFont* functions and is used lazily // 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(). // 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. static const ImWchar icons_ranges[] = { 0xf000, 0xf3ff, 0 }; // Will not be copied by AddFont* so keep in scope.
ImFontConfig config; ImFontConfig config;
config.MergeMode = true; config.MergeMode = true;
io.Fonts->AddFontFromFileTTF("DroidSans.ttf", 18.0f, &config, io.Fonts->GetGlyphRangesJapanese()); 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("fontawesome-webfont.ttf", 18.0f, &config, icons_ranges);
io.Fonts->Build(); io.Fonts->Build();
Add a fourth parameter to bake specific font ranges only: Add a fourth parameter to bake specific font ranges only:
// Basic Latin, Extended Latin // Basic Latin, Extended Latin
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesDefault()); io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesDefault());
// Default + Selection of 2500 Ideographs used by Simplified Chinese // Default + Selection of 2500 Ideographs used by Simplified Chinese
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesChineseSimplifiedCommon()); io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesChineseSimplifiedCommon());
// Default + Hiragana, Katakana, Half-Width, Selection of 1946 Ideographs // Default + Hiragana, Katakana, Half-Width, Selection of 1946 Ideographs
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesJapanese()); io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesJapanese());
See "BUILDING CUSTOM GLYPH RANGES" section to create your own ranges. See "BUILDING CUSTOM GLYPH RANGES" section to create your own ranges.
Offset font vertically by altering the io.Font->DisplayOffset value: Offset font vertically by altering the io.Font->DisplayOffset value:
ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels); ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
font->DisplayOffset.y = 1; // Render 1 pixel down font->DisplayOffset.y = 1; // Render 1 pixel down
--------------------------------------- ---------------------------------------
FREETYPE RASTERIZER, SMALL FONT SIZES FREETYPE RASTERIZER, SMALL FONT SIZES
--------------------------------------- ---------------------------------------
Dear ImGui uses imstb_truetype.h to rasterize fonts (with optional oversampling). 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 This technique and its implementation are not ideal for fonts rendered at _small sizes_, which may appear a
little blurry or hard to read. 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/ folder.
FreeType supports auto-hinting which tends to improve the readability of small fonts. FreeType supports auto-hinting which tends to improve the readability of small fonts.
Note that this code currently creates textures that are unoptimally too large (could be fixed with some work). Note that 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. Also note that correct sRGB space blending will have an important effect on your font rendering quality.
--------------------------------------- ---------------------------------------
BUILDING CUSTOM GLYPH RANGES BUILDING CUSTOM GLYPH RANGES
--------------------------------------- ---------------------------------------
You can use the ImFontAtlas::GlyphRangesBuilder helper to create glyph ranges based on text input. You can use the ImFontAtlas::GlyphRangesBuilder 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. 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; ImVector<ImWchar> ranges;
ImFontAtlas::GlyphRangesBuilder builder; ImFontAtlas::GlyphRangesBuilder builder;
builder.AddText("Hello world"); // Add a string (here "Hello world" contains 7 unique characters) builder.AddText("Hello world"); // Add a string (here "Hello world" contains 7 unique characters)
builder.AddChar(0x7262); // Add a specific character builder.AddChar(0x7262); // Add a specific character
builder.AddRanges(io.Fonts->GetGlyphRangesJapanese()); // Add one of the default ranges 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) 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->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->Build(); // Build the atlas while 'ranges' is still in scope and not deleted.
--------------------------------------- ---------------------------------------
EMBEDDING FONTS IN SOURCE CODE EMBEDDING FONTS IN SOURCE CODE
--------------------------------------- ---------------------------------------
Compile and use 'binary_to_compressed_c.cpp' to create a compressed C style array that you can embed in source code. Compile and use '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 for instruction on how to use the tool. See the documentation in binary_to_compressed_c.cpp for instruction on how to use the tool.
You may find a precompiled version binary_to_compressed_c.exe for Windows instead of demo binaries package (see README). You may find a precompiled version binary_to_compressed_c.exe for Windows instead of demo binaries package (see README).
The tool optionally used Base85 encoding to reduce the size of _source code_ but the read-only arrays will be about 20% bigger. The tool optionally used Base85 encoding to reduce the size of _source code_ but the read-only arrays will be about 20% bigger.
Then load the font with: Then load the font with:
ImFont* font = io.Fonts->AddFontFromMemoryCompressedTTF(compressed_data, compressed_data_size, size_pixels, ...); ImFont* font = io.Fonts->AddFontFromMemoryCompressedTTF(compressed_data, compressed_data_size, size_pixels, ...);
or: or:
ImFont* font = io.Fonts->AddFontFromMemoryCompressedBase85TTF(compressed_data_base85, size_pixels, ...); ImFont* font = io.Fonts->AddFontFromMemoryCompressedBase85TTF(compressed_data_base85, size_pixels, ...);
--------------------------------------- ---------------------------------------
CREDITS/LICENSES FOR FONTS INCLUDED IN THIS FOLDER CREDITS/LICENSES FOR FONTS INCLUDED IN THIS FOLDER
--------------------------------------- ---------------------------------------
Roboto-Medium.ttf Roboto-Medium.ttf
Apache License 2.0
by Christian Robertson
https://fonts.google.com/specimen/Roboto
Cousine-Regular.ttf Apache License 2.0
by Steve Matteson by Christian Robertson
Digitized data copyright (c) 2010 Google Corporation. https://fonts.google.com/specimen/Roboto
Licensed under the SIL Open Font License, Version 1.1
https://fonts.google.com/specimen/Cousine
DroidSans.ttf Cousine-Regular.ttf
Copyright (c) Steve Matteson
Apache License, version 2.0
https://www.fontsquirrel.com/fonts/droid-sans
ProggyClean.ttf by Steve Matteson
Copyright (c) 2004, 2005 Tristan Grimmer Digitized data copyright (c) 2010 Google Corporation.
MIT License Licensed under the SIL Open Font License, Version 1.1
recommended loading setting in ImGui: Size = 13.0, DisplayOffset.Y = +1 https://fonts.google.com/specimen/Cousine
http://www.proggyfonts.net/
ProggyTiny.ttf DroidSans.ttf
Copyright (c) 2004, 2005 Tristan Grimmer
MIT License
recommended loading setting in ImGui: Size = 10.0, DisplayOffset.Y = +1
http://www.proggyfonts.net/
Karla-Regular.ttf Copyright (c) Steve Matteson
Copyright (c) 2012, Jonathan Pinhorn Apache License, version 2.0
SIL OPEN FONT LICENSE Version 1.1 https://www.fontsquirrel.com/fonts/droid-sans
ProggyClean.ttf
Copyright (c) 2004, 2005 Tristan Grimmer
MIT License
recommended loading setting in ImGui: Size = 13.0, DisplayOffset.Y = +1
http://www.proggyfonts.net/
ProggyTiny.ttf
Copyright (c) 2004, 2005 Tristan Grimmer
MIT License
recommended loading setting in ImGui: 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
--------------------------------------- ---------------------------------------
LINKS, OTHER FONTS FONTS LINKS
--------------------------------------- ---------------------------------------
(Icons) Icon fonts ICON FONTS
https://fortawesome.github.io/Font-Awesome/
https://github.com/SamBrishes/kenney-icon-font
https://design.google.com/icons/
You can use https://github.com/juliettef/IconFontCppHeaders for C/C++ header files with name #define to access icon codepoint in source code.
(Icons) IcoMoon - Custom Icon font builder C/C++ header for icon fonts (#define with code points to use in source code string literals)
https://icomoon.io/app https://github.com/juliettef/IconFontCppHeaders
(Pixel perfect) Sweet16, Sweet16 Mono, by Martin Sedlak (Latin + Supplemental + Extended A) FontAwesome
https://github.com/kmar/Sweet16Font https://fortawesome.github.io/Font-Awesome
Also include .inl file to use directly in dear imgui.
(Regular) Open Sans Fonts OpenFontIcons
https://fonts.google.com/specimen/Open+Sans https://github.com/traverseda/OpenFontIcons
(Regular) Google Noto Fonts (worldwide languages) Google Icon Fonts
https://www.google.com/get/noto/ https://design.google.com/icons/
Kenney Icon Font (Game Controller Icons)
https://github.com/nicodinh/kenney-icon-font
(Monospace) Typefaces for source code beautification IcoMoon - Custom Icon font builder
https://github.com/chrissimpkins/codeface https://icomoon.io/app
(Monospace) Programmation fonts REGULAR FONTS
http://s9w.github.io/font_compare/
(Monospace) Proggy Programming Fonts Google Noto Fonts (worldwide languages)
http://upperbounds.net https://www.google.com/get/noto/
(Monospace) Inconsolata
http://www.levien.com/type/myfonts/inconsolata.html
(Monospace) Adobe Source Code Pro: Monospaced font family for user interface and coding environments Open Sans Fonts
https://github.com/adobe-fonts/source-code-pro https://fonts.google.com/specimen/Open+Sans
(Monospace) Monospace/Fixed Width Programmer's Fonts (Japanese) M+ fonts by Coji Morishita are free
http://www.lowing.org/fonts/ http://mplus-fonts.sourceforge.jp/mplus-outline-fonts/index-en.html
(Japanese) M+ fonts by Coji Morishita are free and include most useful Kanjis you would need. MONOSPACE FONTS
http://mplus-fonts.sourceforge.jp/mplus-outline-fonts/index-en.html
Or use Arial Unicode or other Unicode fonts provided with Windows for full characters coverage (not sure of their licensing). (Pixel Perfect) Proggy Fonts, by Tristan Grimmer
http://www.proggyfonts.net or http://upperbounds.net
(Pixel Perfect) Sweet16, Sweet16 Mono, by Martin Sedlak (Latin + Supplemental + Extended A)
https://github.com/kmar/Sweet16Font
Also include .inl file to use directly in dear imgui.
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 user interface and 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).

Write Preview
Loading…
Cancel
Save