Skip to content

Example 3: Different Fonts

Jump to bottom
ZahlGraf edited this page Oct 6, 2015 · 6 revisions

IrrIMGUI Examples

Example 3: Different Fonts

In this example we will load different TTF font files and use them to print text to a IMGUI window. The full source can be found at examples/03.DifferentFonts/main.cpp. In this description we will just concentrate on the methods and functions that are related to using different fonts.

  • Loading Font Files: IMGUI allows you to load and use as many TTF font files you want. The IrrIMGUI binding will provide you with some convenience functions, that help you to use those fonts in your application.

    After the initialization of the IMGUI system, only the default font is loaded and ready for usage. However you can simply add new fonts by using the GUI->addFont... methods from the IIMGUIHandle class. Please look at the API documentation to understand how to use the different addFont... methods. Here we will only use the method ImFont * IIMGUIHandle::addFontFromFileTTF(char const *pFileName, float Size).

    The argument pFileName is a constant string with the path to the TTF File to load and Size is the pixel size of the font. You can load any TTF File with any pixel size you want, since the font is scaled automatically to the specified size. However note that some fonts may have an ideal pixel size at which they look best. This function will return a pointer to a ImFont object. The font object is stored inside the IMGUI system for you.

    Attention: Do not load a font inside the main-loop, since then it will be loaded at every frame. Load the fonts you want to use outside of the loop as a preparation for your GUI. Like building up a scene with Irrlicht.
// load the Cousine-Regular.ttf file from the media directory
ImFont *pCousine16 = GUI->addFontFromFileTTF("../../media/Cousine-Regular.ttf", 16.0f);
ImFont *pCousine24 = GUI->addFontFromFileTTF("../../media/Cousine-Regular.ttf", 24.0f);
  • Compiling fonts: After loading the fonts into the IMGUI System, you need to tell the GUI to create a font texture, that contains all loaded fonts and allow the GUI elements to use them. When you use those fonts without creating the texture, you won't see them at the screen.

    Compile all currently loaded fonts by calling the method GUI->compileFonts(); from the IIMGUIHandle class. This method will free up the old texture memory and builds a new texture for the current set of fonts stored inside the IMGUI system.

    After compiling the fonts you can also add more fonts and compile again. The IrrIMGUI library will take care about the memory allocation and to delete unused font texture memory for you.
// load the Cousine-Regular.ttf file from the media directory
ImFont *pCousine16 = GUI->addFontFromFileTTF("../../media/Cousine-Regular.ttf", 16.0f);
ImFont *pCousine24 = GUI->addFontFromFileTTF("../../media/Cousine-Regular.ttf", 24.0f);
GUI->compileFonts();
  • Using a font: Inside the main loop, you can switch to another font by using the functions ImGui::PushFont(ImFont * pFont) and ImGui::PopFont(). The first function will push the font object that is addressed by the pointer pFont at top of the font-stack. This means, all upcoming IMGUI elements will use this font instead of the font that have been used before. To switch back to the previous font you can use the the ImGui::PopFont() function.

    Attention: After pushing a font to the font-stack, you need to pop it from the stack until the end of the frame is reached. Otherwise you would start push every frame the same font on top of the stack without deleting it from there. This would result in a stack-overflow. IMGUI is throwing an assertion when it detects pushes without pops.
    ImGui::Begin("Different Fonts", NULL, ImGuiWindowFlags_ShowBorders);
    ImGui::Text("Default Font");

    ImGui::PushFont(pCousine16);
    ImGui::Text("Cousine-Regular.ttf; 16px");
    ImGui::PopFont(); // switch back to last font (in this case default)

    ImGui::PushFont(pCousine24);
    ImGui::Text("Cousine-Regular.ttf; 24px");
    ImGui::PopFont(); // switch back to last font (in this case default)

    ImGui::End();

  • Reset Fonts to default: When you use IMGUI in a complex project with many different scenes, you may also want to reset the fonts to the default state. This could be done by calling the method GUI->resetFonts(); of the IIMGUIHandle class. This will delete any Font object stored inside the IMGUI system and restores the default font as the only loaded font. It will also automatically compile the new font texture, that just uses the default font.

    Attention: After resetting the fonts, you are not allowed to use any previously loaded font object with ImGui::PushFont(..) or ImGui::PopFont(). Ensure in your code, that all further GUI elements will just use the default font.

  • Do I need to delete fonts manually?: The font objects, created by the addFont... methods of the IIMGUIHandle class are stored and managed inside the IMGUI system. So you must not delete them inside your application. If you want to free up the font related memory, you can use IIMGUIHandle::resetFonts() to delete them from the IMGUI system or just destroy the last IIMGUIHandle instance to shut-down the IMGUI system and to free up all GUI related memory.

    However: Some addFont... methods allow loading a font from an internal data array instead of loading it from a file. Some of those methods will own the data memory later and will free-up the array automatically after deleting the font from the GUI system. Other methods don't own the data memory array after loading it and thus they won't free up it's memory automatically. Please look at the API documentation of those functions to understand their behaviour.

Clone this wiki locally