Font documentation update (#1498)

extra_fonts/README.txt

@@ -6,20 +6,43 @@
 (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().
+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 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
    #include "IconsFontAwesome.h"
    ImGuiIO& io = ImGui::GetIO();
    io.Fonts->AddFontDefault();
+
    ImFontConfig config;
    config.MergeMode = true;
    static const ImWchar icon_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };
@@ -28,10 +51,12 @@
    // Usage, e.g.
    ImGui::Text("%s Search", ICON_FA_SEARCH);
 
+ See Links below for other icons fonts and related tools.
 
----------------------------------
+
+---------------------------------------
  FONTS LOADING INSTRUCTIONS
----------------------------------
+---------------------------------------
 
  Load default font with:
 
@@ -43,7 +68,7 @@
    ImGuiIO& io = ImGui::GetIO();
    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;
    config.OversampleH = 3;
@@ -89,9 +114,23 @@
    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
----------------------------------
+---------------------------------------
 
  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. 
@@ -105,9 +144,9 @@
    io.Fonts->AddFontFromFileTTF("myfontfile.ttf", size_in_pixels, NULL, ranges.Data);
 
 
----------------------------------
+---------------------------------------
  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!
  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.
 
 
----------------------------------
+---------------------------------------
- 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.
  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, ...);
 
 
----------------------------------
+---------------------------------------
- FONT FILES INCLUDED IN THIS FOLDER
+ CREDITS/LICENSES FOR FONTS INCLUDED IN THIS FOLDER
----------------------------------
+---------------------------------------
 
  Roboto-Medium.ttf
    Apache License 2.0
@@ -172,9 +211,9 @@
    SIL OPEN FONT LICENSE Version 1.1
 
 
----------------------------------
+---------------------------------------
- LINKS & OTHER FONTS
+ LINKS, OTHER FONTS
----------------------------------
+---------------------------------------
 
  (Icons) Icon fonts
    https://fortawesome.github.io/Font-Awesome/
@@ -213,3 +252,4 @@
    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).
+