imgui/misc/freetype/README.md

# imgui_freetype

Build font atlases using FreeType instead of stb_truetype (which is the default font rasterizer).
<br>by @vuhdo, @mikesart, @ocornut.

### Usage

1. Get latest FreeType binaries or build yourself (under Windows you may use vcpkg with `vcpkg install freetype --triplet=x64-windows`, `vcpkg integrate install`).
2. Add imgui_freetype.h/cpp alongside your project files.
3. Add `#define IMGUI_ENABLE_FREETYPE` in your [imconfig.h](https://github.com/ocornut/imgui/blob/master/imconfig.h) file

### About Gamma Correct Blending

FreeType assumes blending in linear space rather than gamma space.
See FreeType note for [FT_Render_Glyph](https://www.freetype.org/freetype2/docs/reference/ft2-base_interface.html#FT_Render_Glyph).
For correct results you need to be using sRGB and convert to linear space in the pixel shader output.
The default Dear ImGui styles will be impacted by this change (alpha values will need tweaking).

### Testbed for toying with settings (for developers)

See https://gist.github.com/ocornut/b3a9ecf13502fd818799a452969649ad

### Known issues

- Oversampling settins are ignored but also not so much necessary with the higher quality rendering.

### Comparaison

Small, thin anti-aliased fonts typically benefit a lot from FreeType's hinting:
![comparing_font_rasterizers](https://user-images.githubusercontent.com/8225057/107550178-fef87f00-6bd0-11eb-8d09-e2edb2f0ccfc.gif)

### Colorful glyphs/emojis

You can use the `ImGuiFreeTypeBuilderFlags_LoadColor` flag to load certain colorful glyphs. See the
["Using Colorful Glyphs/Emojis"](https://github.com/ocornut/imgui/edit/master/docs/FONTS.md#using-colorful-glyphsemojis) section of FONTS.md.

![colored glyphs](https://user-images.githubusercontent.com/8225057/106171241-9dc4ba80-6191-11eb-8a69-ca1467b206d1.png)
imgui_freetype: Documentation, tweaks. (#618) 2018-02-04 11:44:31 +00:00			`# imgui_freetype`

Fonts: (Breaking) Rename ImGuiFreeType:: flags to ImGuiFreeTypeBuilderFlags_XXX. Remove ImGuiFreeType::BuildFontAtlas() flags. Rename ImFontConfig::RasterizerFlags to FontBuilderFlags. Add ImFontBuilderIO (opaque). Amend 53d59f3 with a dozen of small fixes. 2021-01-25 16:57:12 +00:00			`Build font atlases using FreeType instead of stb_truetype (which is the default font rasterizer).`
ImFontAtlas: Rewrote FreeType based builder. - Fixed abnormally high atlas height. (#618) - Fixed support for any values of TexGlyphPadding (not just only 1). (#618) - Atlas width is now properly based on total surface rather than glyph count (unless overridden with TexDesiredWidth). (#618) - Fixed atlas builder so missing glyphs won't influence the atlas texture width. (#2233, #618) - Fixed atlas builder so duplicate glyphs (when merging fonts) won't be included in the rasterized atlas. (#618) 2019-01-10 21:11:27 +00:00			`<br>by @vuhdo, @mikesart, @ocornut.`
imgui_freetype: Documentation, tweaks. (#618) 2018-02-04 11:44:31 +00:00
ImFontAtlas: Rewrote FreeType based builder. - Fixed abnormally high atlas height. (#618) - Fixed support for any values of TexGlyphPadding (not just only 1). (#618) - Atlas width is now properly based on total surface rather than glyph count (unless overridden with TexDesiredWidth). (#618) - Fixed atlas builder so missing glyphs won't influence the atlas texture width. (#2233, #618) - Fixed atlas builder so duplicate glyphs (when merging fonts) won't be included in the rasterized atlas. (#618) 2019-01-10 21:11:27 +00:00			`### Usage`

Examples: SDL2: Accomodate for vcpkg install having headers in SDL2/SDL.h vs SDL.h + vcpkg related comments. 2021-06-08 13:20:47 +00:00			1. Get latest FreeType binaries or build yourself (under Windows you may use vcpkg with `vcpkg install freetype --triplet=x64-windows`, `vcpkg integrate install`).
Fonts: (Breaking) Rename ImGuiFreeType:: flags to ImGuiFreeTypeBuilderFlags_XXX. Remove ImGuiFreeType::BuildFontAtlas() flags. Rename ImFontConfig::RasterizerFlags to FontBuilderFlags. Add ImFontBuilderIO (opaque). Amend 53d59f3 with a dozen of small fixes. 2021-01-25 16:57:12 +00:00			`2. Add imgui_freetype.h/cpp alongside your project files.`
			3. Add `#define IMGUI_ENABLE_FREETYPE` in your [imconfig.h](https://github.com/ocornut/imgui/blob/master/imconfig.h) file
imgui_freetype: Documentation, tweaks. (#618) 2018-02-04 11:44:31 +00:00
Fonts: (Breaking) Rename ImGuiFreeType:: flags to ImGuiFreeTypeBuilderFlags_XXX. Remove ImGuiFreeType::BuildFontAtlas() flags. Rename ImFontConfig::RasterizerFlags to FontBuilderFlags. Add ImFontBuilderIO (opaque). Amend 53d59f3 with a dozen of small fixes. 2021-01-25 16:57:12 +00:00			`### About Gamma Correct Blending`
ImFontAtlas: Rewrote FreeType based builder. - Fixed abnormally high atlas height. (#618) - Fixed support for any values of TexGlyphPadding (not just only 1). (#618) - Atlas width is now properly based on total surface rather than glyph count (unless overridden with TexDesiredWidth). (#618) - Fixed atlas builder so missing glyphs won't influence the atlas texture width. (#2233, #618) - Fixed atlas builder so duplicate glyphs (when merging fonts) won't be included in the rasterized atlas. (#618) 2019-01-10 21:11:27 +00:00
imgui_freetype: comments about correct blending and sRGB (#618, #578) 2018-02-05 10:21:06 +00:00			`FreeType assumes blending in linear space rather than gamma space.`
			`See FreeType note for [FT_Render_Glyph](https://www.freetype.org/freetype2/docs/reference/ft2-base_interface.html#FT_Render_Glyph).`
			`For correct results you need to be using sRGB and convert to linear space in the pixel shader output.`
Readme, comments, dear imgui prefixes 2019-06-11 14:11:19 +00:00			`The default Dear ImGui styles will be impacted by this change (alpha values will need tweaking).`
imgui_freetype: comments about correct blending and sRGB (#618, #578) 2018-02-05 10:21:06 +00:00
Fonts: (Breaking) Rename ImGuiFreeType:: flags to ImGuiFreeTypeBuilderFlags_XXX. Remove ImGuiFreeType::BuildFontAtlas() flags. Rename ImFontConfig::RasterizerFlags to FontBuilderFlags. Add ImFontBuilderIO (opaque). Amend 53d59f3 with a dozen of small fixes. 2021-01-25 16:57:12 +00:00			`### Testbed for toying with settings (for developers)`
imgui_freetype: Documentation, tweaks. (#618) 2018-02-04 11:44:31 +00:00
Fonts: (Breaking) Rename ImGuiFreeType:: flags to ImGuiFreeTypeBuilderFlags_XXX. Remove ImGuiFreeType::BuildFontAtlas() flags. Rename ImFontConfig::RasterizerFlags to FontBuilderFlags. Add ImFontBuilderIO (opaque). Amend 53d59f3 with a dozen of small fixes. 2021-01-25 16:57:12 +00:00			`See https://gist.github.com/ocornut/b3a9ecf13502fd818799a452969649ad`
imgui_freetype: Documentation, tweaks. (#618) 2018-02-04 11:44:31 +00:00
ImFontAtlas: Rewrote FreeType based builder. - Fixed abnormally high atlas height. (#618) - Fixed support for any values of TexGlyphPadding (not just only 1). (#618) - Atlas width is now properly based on total surface rather than glyph count (unless overridden with TexDesiredWidth). (#618) - Fixed atlas builder so missing glyphs won't influence the atlas texture width. (#2233, #618) - Fixed atlas builder so duplicate glyphs (when merging fonts) won't be included in the rasterized atlas. (#618) 2019-01-10 21:11:27 +00:00			`### Known issues`
imgui_freetype: Documentation, tweaks. (#618) 2018-02-04 11:44:31 +00:00
Version 1.81 2021-02-10 17:47:46 +00:00			`- Oversampling settins are ignored but also not so much necessary with the higher quality rendering.`

			`### Comparaison`

Correct typos (#4954, #4955), use IM_STATIC_ASSERT now that old pre-C++11 macro has been obsoleted. 2022-01-27 17:52:00 +00:00			`Small, thin anti-aliased fonts typically benefit a lot from FreeType's hinting:`
Version 1.81 2021-02-10 17:47:46 +00:00			`![comparing_font_rasterizers](https://user-images.githubusercontent.com/8225057/107550178-fef87f00-6bd0-11eb-8d09-e2edb2f0ccfc.gif)`
Docs: Improvements to description of using colored glyphes/emojis. (#4169, #3369) + Add Fonts to Metrics. Removed IMGUI_HAS_TABLE markers. 2021-05-24 10:49:58 +00:00
			`### Colorful glyphs/emojis`

Correct typos (#4954, #4955), use IM_STATIC_ASSERT now that old pre-C++11 macro has been obsoleted. 2022-01-27 17:52:00 +00:00			You can use the `ImGuiFreeTypeBuilderFlags_LoadColor` flag to load certain colorful glyphs. See the
Docs: Improvements to description of using colored glyphes/emojis. (#4169, #3369) + Add Fonts to Metrics. Removed IMGUI_HAS_TABLE markers. 2021-05-24 10:49:58 +00:00			`["Using Colorful Glyphs/Emojis"](https://github.com/ocornut/imgui/edit/master/docs/FONTS.md#using-colorful-glyphsemojis) section of FONTS.md.`

			`![colored glyphs](https://user-images.githubusercontent.com/8225057/106171241-9dc4ba80-6191-11eb-8a69-ca1467b206d1.png)`