mirrors/imgui
1
Fork 0
mirror of https://github.com/ocornut/imgui.git synced 2024-10-16 16:25:15 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Font documentation update (#1498)

Browse source
This commit is contained in:
omar 2017-12-12 11:20:45 +01:00
parent c65124f415
commit de4a851f95
1 changed files with 67 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

94
extra_fonts/README.txt
View file

@ -1,25 +1,48 @@
The code in imgui.cpp embeds a copy of 'ProggyClean.ttf' (by Tristan Grimmer) that is used by default. The code in imgui.cpp embeds a copy of 'ProggyClean.ttf' (by Tristan Grimmer) that is used by default.
We embed the font in source code so you can use Dear ImGui without any file system access. We embed the font in source code so you can use Dear ImGui without any file system access.
You may also load external .TTF/.OTF files. You may also load external .TTF/.OTF files.
The files in this folder are suggested fonts, provided as a convenience. The files in this folder are suggested fonts, provided as a convenience.
(Note: .OTF support in stb_truetype.h currently doesn't appear to load every font) (Note: .OTF support in stb_truetype.h currently doesn't appear to load every font)
Fonts are rasterized in a single texture at the time of calling either of io.Fonts.GetTexDataAsAlpha8()/GetTexDataAsRGBA32()/Build(). Fonts are rasterized in a single texture at the time of calling either of io.Fonts.GetTexDataAsAlpha8()/GetTexDataAsRGBA32()/Build().
Also read dear imgui FAQ in imgui.cpp!
--------------------------------- In this document:
- Using Icons
- Fonts Loading Instructions
- FreeType rasterizer, Small font sizes
- Building Custom Glyph Ranges
- Remapping Codepoints
- Embedding Fonts in Source Code
- Credits/Licences for fonts included in this folder
- Links, Other fonts
---------------------------------------
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) is an easy and practical way to use icons in your ImGui application.
A common pattern is to merge the icon font within your main font, so you can refer to the icons directly from your strings without 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
To refer to the icon from your C++ code, you can use headers files created by Juliette Foucaut, at https://github.com/juliettef/IconFontCppHeaders having to change fonts back and forth.
See Links below for other icons fonts and related tools.
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
The C++11 version of those files uses the u8"" utf-8 encoding syntax + \u
#define ICON_FA_SEARCH u8"\uf002"
The pre-C++11 version has the values directly encoded as utf-8:
#define ICON_FA_SEARCH "\xEF\x80\x82"
Example:
// 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;
static const ImWchar icon_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 }; static const ImWchar icon_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };
@ -28,10 +51,12 @@
// Usage, e.g. // Usage, e.g.
ImGui::Text("%s Search", ICON_FA_SEARCH); ImGui::Text("%s Search", ICON_FA_SEARCH);
See Links below for other icons fonts and related tools.
---------------------------------
---------------------------------------
FONTS LOADING INSTRUCTIONS FONTS LOADING INSTRUCTIONS
--------------------------------- ---------------------------------------
Load default font with: Load default font with:
@ -43,7 +68,7 @@
ImGuiIO& io = ImGui::GetIO(); ImGuiIO& io = ImGui::GetIO();
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels); io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
Advanced options: 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;
@ -89,9 +114,23 @@
font->DisplayOffset.y += 1; // Render 1 pixel down font->DisplayOffset.y += 1; // Render 1 pixel down
--------------------------------- ---------------------------------------
FREETYPE RASTERIZER, SMALL FONT SIZES
---------------------------------------
Dear Imgui uses stb_truetype.h to rasterize fonts (with optional oversampling).
This technique and implementation are not ideal for fonts rendered at _small sizes_, which may appear a little blurry.
There is an implementation of the ImFontAtlas builder using FreeType that you can use:
https://github.com/ocornut/imgui_club
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)
---------------------------------------
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 exemple: 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 exemple: 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.
@ -105,9 +144,9 @@
io.Fonts->AddFontFromFileTTF("myfontfile.ttf", size_in_pixels, NULL, ranges.Data); io.Fonts->AddFontFromFileTTF("myfontfile.ttf", size_in_pixels, NULL, ranges.Data);
--------------------------------- ---------------------------------------
REMAPPING CODEPOINTS REMAPPING CODEPOINTS
--------------------------------- ---------------------------------------
All your strings needs to use UTF-8 encoding. Specifying literal in your source code using a local code page (such as CP-923 for Japanese, or CP-1251 for Cyrillic) will NOT work! All your strings needs to use UTF-8 encoding. Specifying literal in your source code using a local code page (such as CP-923 for Japanese, or CP-1251 for Cyrillic) will NOT work!
In C++11 you can encode a string literal in UTF-8 by using the u8"hello" syntax. Otherwise you can convert yourself to UTF-8 or load text data from file already saved as UTF-8. In C++11 you can encode a string literal in UTF-8 by using the u8"hello" syntax. Otherwise you can convert yourself to UTF-8 or load text data from file already saved as UTF-8.
@ -117,9 +156,9 @@
You may also try to remap your local codepage characters to their Unicode codepoint using font->AddRemapChar(), but international users may have problems reading/editing your source code. You may also try to remap your local codepage characters to their Unicode codepoint using font->AddRemapChar(), but international users may have problems reading/editing your source code.
--------------------------------- ---------------------------------------
EMBEDDING FONT 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.
@ -135,9 +174,9 @@
ImFont* font = io.Fonts->AddFontFromMemoryCompressedBase85TTF(compressed_data_base85, size_pixels, ...); ImFont* font = io.Fonts->AddFontFromMemoryCompressedBase85TTF(compressed_data_base85, size_pixels, ...);
--------------------------------- ---------------------------------------
FONT FILES INCLUDED IN THIS FOLDER CREDITS/LICENSES FOR FONTS INCLUDED IN THIS FOLDER
--------------------------------- ---------------------------------------
Roboto-Medium.ttf Roboto-Medium.ttf
Apache License 2.0 Apache License 2.0
@ -172,9 +211,9 @@
SIL OPEN FONT LICENSE Version 1.1 SIL OPEN FONT LICENSE Version 1.1
--------------------------------- ---------------------------------------
LINKS & OTHER FONTS LINKS, OTHER FONTS
--------------------------------- ---------------------------------------
(Icons) Icon fonts (Icons) Icon fonts
https://fortawesome.github.io/Font-Awesome/ https://fortawesome.github.io/Font-Awesome/
@ -213,3 +252,4 @@
http://mplus-fonts.sourceforge.jp/mplus-outline-fonts/index-en.html 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). Or use Arial Unicode or other Unicode fonts provided with Windows for full characters coverage (not sure of their licensing).