imgui/docs/FONTS.md

## Fonts

The code in imgui.cpp embeds a copy of 'ProggyClean.ttf' (by Tristan Grimmer),
a 13 pixels high, pixel-perfect font used by default. We embed it font in source code so you can use Dear ImGui without any file system access.

You may also load external .TTF/.OTF files. The files in this folder are suggested fonts, provided as a convenience.

Fonts are rasterized in a single texture at the time of calling either of 

- `io.Fonts->GetTexDataAsAlpha8()`

- `GetTexDataAsRGBA32()/Build()`

**Please read the FAQ:** https://www.dearimgui.org/faq
Please use the Discord server: http://discord.dearimgui.org and not the GitHub issue tracker for basic font loading questions.


---------------------------------------
| Index |
|:---------------------------------------|
| [Readme First](#readme-first) |
| [Using Icons](#using-icons) |
| [Fonts Loading Instructions](#font-loading-instructions) |
| [FreeType Rasterizer, Small Font Sizes](#freeType-rasterizer-small-font-sizes) |
| [Building Custom Glyph Ranges](#building-custom-glyph-ranges) |
| [Using Custom Colorful Icons](#using-custom-colorful-icons) |
| [Embedding Fonts In Source Code](#embedding-fonts-in-source-code) |
| [Credits/Licenses For Fonts Included In This Folder](#creditslicenses-for-fonts-included-in-this-folder) |
| [Font Links](#font-links) |


---------------------------------------
 ## Readme First

- You can use the style editor ImGui::ShowStyleEditor() in the "Fonts" section 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".


---------------------------------------
 ## 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

**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 Setup:
```cpp
  // 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);
```
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"
```
See Links below for other icons fonts and related tools.


---------------------------------------
 ## Font Loading Instructions

Load default font:
```cpp
  ImGuiIO& io = ImGui::GetIO();
  io.Fonts->AddFontDefault();
```
Load .TTF/.OTF file with:
```cpp
  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):
```cpp
  ImFontConfig config;
  config.OversampleH = 2;
  config.OversampleV = 1;
  config.GlyphExtraSpacing.x = 1.0f;
  ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, &config);
```
**Read about oversampling [here](https://github.com/nothings/stb/blob/master/tests/oversample)**

- 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 ImFontGlyphRangesBuilder 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:
```cpp
  // 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:
```cpp
  // 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 + Hiragana, Katakana, Half-Width, Selection of 1946 Ideographs
  io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, NULL, io.Fonts->GetGlyphRangesJapanese());
```
See [Building Custom Glyph Ranges](#building-custom-glyph-ranges) section to create your own ranges.
Offset font vertically by altering the io.Font->DisplayOffset value:
```cpp
  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.
- 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** 
- 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 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)

  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.
```

---------------------------------------
## Using Custom Colorful Icons

**(This is a BETA api, use if you are familiar with dear imgui and with your rendering back-end)**

- You can use the ImFontAtlas::AddCustomRect() and ImFontAtlas::AddCustomRectFontGlyph() api to register rectangles that will be packed into the font atlas texture. Register them before building the atlas, then call Build().
- You can then use ImFontAtlas::GetCustomRectByIndex(int) to query the position/size of your rectangle within the texture, and blit/copy any graphics data of your choice into those rectangles.

#### Pseudo-code:
```
  // 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();

  // 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);
          }
      }
  }
```

---------------------------------------
 ## 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 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, ...); `
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

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
  http://www.proggyfonts.net/

ProggyTiny.ttf
  Copyright (c) 2004, 2005 Tristan Grimmer
  MIT License
  recommended loading setting: 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


---------------------------------------
 ## Font Links

#### ICON FONTS

  C/C++ header for icon fonts (#define with code points to use in source code string literals)
  https://github.com/juliettef/IconFontCppHeaders

  FontAwesome
  https://fortawesome.github.io/Font-Awesome

  OpenFontIcons
  https://github.com/traverseda/OpenFontIcons

  Google Icon Fonts
  https://design.google.com/icons/

  Kenney Icon Font (Game Controller Icons)
  https://github.com/nicodinh/kenney-icon-font

  IcoMoon - Custom Icon font builder
  https://icomoon.io/app

#### REGULAR FONTS

  Google Noto Fonts (worldwide languages)
  https://www.google.com/get/noto/

  Open Sans Fonts
  https://fonts.google.com/specimen/Open+Sans

  (Japanese) M+ fonts by Coji Morishita are free
  http://mplus-fonts.sourceforge.jp/mplus-outline-fonts/index-en.html

#### MONOSPACE FONTS

  (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.

  Google Noto Mono Fonts
  https://www.google.com/get/noto/

  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).