1
0
mirror of https://github.com/ocornut/imgui.git synced 2024-12-05 04:28:01 +01:00
imgui/extra_fonts
Ben Vanik 6ec50d6bf5 Fix binary_to_compressed_c tool to return 0 when successful
Returning 1 is seen as an error by many tools, making it tricky to integrate this into build systems as-is.
2017-10-03 11:45:25 -07:00
..
binary_to_compressed_c.cpp Fix binary_to_compressed_c tool to return 0 when successful 2017-10-03 11:45:25 -07:00
Cousine-Regular.ttf Fonts: added Cousine-Regular.ttf 2015-07-15 14:56:29 -06:00
DroidSans.ttf Added DroidSans.ttf font in repository 2015-02-01 13:06:56 +00:00
Karla-Regular.ttf Cleanup extra_fonts/ folder 2015-01-08 23:49:17 +00:00
ProggyClean.ttf Cleanup extra_fonts/ folder 2015-01-08 23:49:17 +00:00
ProggyTiny.ttf Cleanup extra_fonts/ folder 2015-01-08 23:49:17 +00:00
README.txt Fonts: Adding references to the fact that .OTF fonts are supported (but haven't renamed the entry points) 2017-08-14 11:29:54 +08:00
Roboto-Medium.ttf Font: Added Roboto-Medium + tweaked readme 2016-11-06 22:21:10 +01:00

 The code in imgui.cpp embeds a copy of 'ProggyClean.ttf' that you can use without any external files.
 The files in this folder are only provided as a convenience, you can use any .TTF/.OTF.
 (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().

---------------------------------
 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.
 To refer to the icon from your C++ code, you can use headers files created by Juliette Foucaut, at https://github.com/juliettef/IconFontCppHeaders

    // 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 };
   io.Fonts->AddFontFromFileTTF("fonts/fontawesome-webfont.ttf", 13.0f, &config, icon_ranges);

   // Usage, e.g.
   ImGui::Text("%s Search", ICON_FA_SEARCH);


---------------------------------
 FONTS LOADING INSTRUCTIONS
---------------------------------

 Load default font with:

   ImGuiIO& io = ImGui::GetIO();
   io.Fonts->AddFontDefault();

 Load .TTF/.OTF file with:

   ImGuiIO& io = ImGui::GetIO();
   io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
  
 Detailed options:

   ImFontConfig config;
   config.OversampleH = 3;
   config.OversampleV = 1;
   config.GlyphExtraSpacing.x = 1.0f;
   io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, &config);

 If you have very large number of glyphs or multiple fonts:

  - Mind the fact that some graphics drivers have texture size limitation.
  - Set io.Fonts.TexDesiredWidth to specify a texture width to minimize texture height (see comment in ImFontAtlas::Build function).
  - You may reduce oversampling, e.g. config.OversampleH = 2 or 1.
  - Reduce glyphs ranges, consider calculating them based on your source data if this is possible.

 Combine two fonts into one:

   // Load a first 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 for duration of font usage
   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);

 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());
   
   // Include full set of about 21000 CJK Unified 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->GetGlyphRangesChinese());

 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


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

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


---------------------------------
 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 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.
 You can 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
---------------------------------

 Compile and use 'binary_to_compressed_c.cpp' to create a compressed C style array. 
 See the documentation in binary_to_compressed_c.cpp for instruction on how to use the tool.
 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, ...);


---------------------------------
 FONT FILES 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
   http://www.google.com/fonts/specimen/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
---------------------------------

 Icon fonts
   https://fortawesome.github.io/Font-Awesome/
   https://github.com/SamBrishes/kenney-icon-font
   https://design.google.com/icons/

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

 Typefaces for source code beautification
   https://github.com/chrissimpkins/codeface
 
 Programmation fonts
   http://s9w.github.io/font_compare/

 Proggy Programming Fonts
   http://upperbounds.net
   
 Inconsolata
   http://www.levien.com/type/myfonts/inconsolata.html

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

 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/

 (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

 Or use Arial Unicode or other Unicode fonts provided with Windows for full characters coverage (not sure of their licensing).