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://freetype.org/freetype2/docs/reference/ft2-glyph_retrieval.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 settings are ignored but also not so much necessary with the higher quality rendering.

### Comparison

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/blob/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)

### Using OpenType SVG fonts (SVGinOT)
- *SVG in Open Type* is a standard by Adobe and Mozilla for color OpenType and Open Font Format fonts. It allows font creators to embed complete SVG files within a font enabling full color and even animations.
- Popular fonts such as [twemoji](https://github.com/13rac1/twemoji-color-font) and fonts made with [scfbuild](https://github.com/13rac1/scfbuild) is SVGinOT
- Requires: [lunasvg](https://github.com/sammycage/lunasvg) v2.3.2 and above
    1. Add `#define IMGUI_ENABLE_FREETYPE_LUNASVG` in your `imconfig.h`.
    2. Get latest lunasvg binaries or build yourself. Under Windows you may use vcpkg with: `vcpkg install lunasvg --triplet=x64-windows`.
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.`
Docs: Fix outdated link in freetype docs (#6568) 2023-07-04 10:23:13 +00:00			`See FreeType note for [FT_Render_Glyph](https://freetype.org/freetype2/docs/reference/ft2-glyph_retrieval.html#ft_render_glyph).`
imgui_freetype: comments about correct blending and sRGB (#618, #578) 2018-02-05 10:21:06 +00:00			`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
Fonts: Amends for support for OpenType SVG fonts using lunasvg (#6591, #6607) 2023-08-01 07:33:56 +00:00			`- Oversampling settings are ignored but also not so much necessary with the higher quality rendering.`
Version 1.81 2021-02-10 17:47:46 +00:00
imgui_freetype: fix warnings (#6104), fix typos. (#6079) 2023-01-24 14:59:01 +00:00			`### Comparison`
Version 1.81 2021-02-10 17:47:46 +00:00
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
Changed FONT.md edit to blob (#5290) Stop from opening the editor for freetype/README.md 2022-05-06 07:47:18 +00:00			`["Using Colorful Glyphs/Emojis"](https://github.com/ocornut/imgui/blob/master/docs/FONTS.md#using-colorful-glyphsemojis) section of FONTS.md.`
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
			`![colored glyphs](https://user-images.githubusercontent.com/8225057/106171241-9dc4ba80-6191-11eb-8a69-ca1467b206d1.png)`
Fonts: Added support for OpenType SVG fonts using lunasvg (#6591, #6607) 2023-08-01 07:27:08 +00:00
			`### Using OpenType SVG fonts (SVGinOT)`
			`- SVG in Open Type is a standard by Adobe and Mozilla for color OpenType and Open Font Format fonts. It allows font creators to embed complete SVG files within a font enabling full color and even animations.`
			`- Popular fonts such as [twemoji](https://github.com/13rac1/twemoji-color-font) and fonts made with [scfbuild](https://github.com/13rac1/scfbuild) is SVGinOT`
			`- Requires: [lunasvg](https://github.com/sammycage/lunasvg) v2.3.2 and above`
Fonts: Amends for support for OpenType SVG fonts using lunasvg (#6591, #6607) 2023-08-01 07:33:56 +00:00			1. Add `#define IMGUI_ENABLE_FREETYPE_LUNASVG` in your `imconfig.h`.
			2. Get latest lunasvg binaries or build yourself. Under Windows you may use vcpkg with: `vcpkg install lunasvg --triplet=x64-windows`.