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

misc/fonts/README.txt

@@ -32,259 +32,279 @@ If you have other loading/merging/adding fonts, you can post on the Dear ImGui "
  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.
- - 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.:
-       u8"hello"
-       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".
- - Please use the Discourse forum (https://discourse.dearimgui.org) and not the Github issue tracker for basic font loading questions.
+- 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().
+- Use C++11 u8"my text" syntax to encode literal strings as UTF-8. e.g.:
+      u8"hello"
+      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".
+- Please use the Discourse forum (https://discourse.dearimgui.org) and not the Github issue tracker for basic font loading questions.
 
 
 ---------------------------------------
  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.
- 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.
+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
+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"
+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:
+Example Setup:
 
-    // 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);
 
-   // Usage, e.g.
-   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" 
+Example Usage:
 
-   // Usage, e.g.
-   ImGui::Text("%s among %d items", ICON_FA_SEARCH, count);
+  // 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.
+See Links below for other icons fonts and related tools.
 
 
 ---------------------------------------
  FONTS LOADING INSTRUCTIONS
 ---------------------------------------
 
- Load default font:
+Load default font:
 
-   ImGuiIO& io = ImGui::GetIO();
-   io.Fonts->AddFontDefault();
+  ImGuiIO& io = ImGui::GetIO();
+  io.Fonts->AddFontDefault();
 
- Load .TTF/.OTF file with:
+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);
+  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 = 3;
-   config.OversampleV = 1;
-   config.GlyphExtraSpacing.x = 1.0f;
-   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.
- 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 
- set OversampleH/OversampleV to 1 and use a small font size.
- 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.
- Some solutions:
-
-  - 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. 
-  - 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).
-  - 4) Set io.Fonts.Flags |= ImFontAtlasFlags_NoPowerOfTwoHeight; to disable rounding the texture height to the next power of two.
-
- 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());
+  // 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 = 3;
+  config.OversampleV = 1;
+  config.GlyphExtraSpacing.x = 1.0f;
+  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.
+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 
+set OversampleH/OversampleV to 1 and use a small font size.
+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.
+Some solutions:
+
+ - 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. 
+ - 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).
+ - 4) Set io.Fonts.Flags |= ImFontAtlasFlags_NoPowerOfTwoHeight; to disable rounding the texture height to the next power of two.
+
+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 + 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());
+  // 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:
+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
+  ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
+  font->DisplayOffset.y = 1;   // Render 1 pixel down
 
 
 ---------------------------------------
  FREETYPE RASTERIZER, SMALL FONT SIZES
 ---------------------------------------
 
- 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. 
+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/ folder.
 
- 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).
- Also note that correct sRGB space blending will have an important effect on your font rendering quality.
+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).
+Also note that correct sRGB space blending will have an important effect on your font rendering quality.
 
 
 ---------------------------------------
  BUILDING CUSTOM GLYPH RANGES
 ---------------------------------------
 
- 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. 
+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. 
 
-   ImVector<ImWchar> ranges;
-   ImFontAtlas::GlyphRangesBuilder 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;
+  ImFontAtlas::GlyphRangesBuilder 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.
 
 
 ---------------------------------------
  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.
- 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).
- The tool optionally used Base85 encoding to reduce the size of _source code_ but the read-only arrays will be about 20% bigger. 
+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.
+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. 
 
- 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, ...);
+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, ...);
 
 
 ---------------------------------------
  CREDITS/LICENSES FOR FONTS INCLUDED IN THIS FOLDER
 ---------------------------------------
 
- Roboto-Medium.ttf
-   Apache License 2.0
-   by Christian Robertson
-   https://fonts.google.com/specimen/Roboto
+Roboto-Medium.ttf
 
- 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 
+  Apache License 2.0
+  by Christian Robertson
+  https://fonts.google.com/specimen/Roboto
 
- DroidSans.ttf
-   Copyright (c) Steve Matteson
-   Apache License, version 2.0
-   https://www.fontsquirrel.com/fonts/droid-sans
+Cousine-Regular.ttf
 
- 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/
+  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 
 
- 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/
+DroidSans.ttf
 
- Karla-Regular.ttf
-   Copyright (c) 2012, Jonathan Pinhorn
-   SIL OPEN FONT LICENSE Version 1.1
+  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 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
-   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.
+ICON FONTS
 
- (Icons) IcoMoon - Custom Icon font builder
-   https://icomoon.io/app
+  C/C++ header for icon fonts (#define with code points to use in source code string literals)
+  https://github.com/juliettef/IconFontCppHeaders
 
- (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.
+  FontAwesome
+  https://fortawesome.github.io/Font-Awesome
 
- (Regular) Open Sans Fonts
-   https://fonts.google.com/specimen/Open+Sans
+  OpenFontIcons
+  https://github.com/traverseda/OpenFontIcons
 
- (Regular) Google Noto Fonts (worldwide languages)
-   https://www.google.com/get/noto/
+  Google Icon Fonts
+  https://design.google.com/icons/
+
+  Kenney Icon Font (Game Controller Icons)
+  https://github.com/nicodinh/kenney-icon-font
  
- (Monospace) Typefaces for source code beautification
-   https://github.com/chrissimpkins/codeface
+  IcoMoon - Custom Icon font builder
+  https://icomoon.io/app
 
- (Monospace) Programmation fonts
-   http://s9w.github.io/font_compare/
+REGULAR FONTS
 
- (Monospace) Proggy Programming Fonts
-   http://upperbounds.net
-   
- (Monospace) Inconsolata
-   http://www.levien.com/type/myfonts/inconsolata.html
+  Google Noto Fonts (worldwide languages)
+  https://www.google.com/get/noto/
 
- (Monospace) Adobe Source Code Pro: Monospaced font family for user interface and coding environments
-   https://github.com/adobe-fonts/source-code-pro
+  Open Sans Fonts
+  https://fonts.google.com/specimen/Open+Sans
 
- (Monospace) Monospace/Fixed Width Programmer's Fonts
-   http://www.lowing.org/fonts/
+  (Japanese) M+ fonts by Coji Morishita are free
+  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.
-   http://mplus-fonts.sourceforge.jp/mplus-outline-fonts/index-en.html
+MONOSPACE FONTS
 
- 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).