From 441c270c195541884f6e44e256ef5368c6a019fe Mon Sep 17 00:00:00 2001 From: Pascal Thomet Date: Thu, 18 Apr 2024 16:09:52 +0200 Subject: [PATCH] Update docs / 2024-04-18 / 16:09:52 --- docs/book/_sources/doc_api.md | 152 ++++++++++++++++----- docs/book/_sources/doc_params.md | 84 +++++++++--- docs/book/build.html | 16 ++- docs/book/doc_api.html | 226 ++++++++++++++++++++++++------- docs/book/doc_params.html | 98 ++++++++++---- docs/book/genindex.html | 5 +- docs/book/get_started.html | 11 +- docs/book/intro.html | 5 +- docs/book/search.html | 5 +- docs/book/searchindex.js | 2 +- 10 files changed, 457 insertions(+), 147 deletions(-) diff --git a/docs/book/_sources/doc_api.md b/docs/book/_sources/doc_api.md index da526d15..75b4470f 100644 --- a/docs/book/_sources/doc_api.md +++ b/docs/book/_sources/doc_api.md @@ -57,8 +57,16 @@ float EmSize(float nbLines); # Load fonts See [hello_imgui_font.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/hello_imgui_font.h). ```cpp + + // When loading fonts, use + // HelloImGui::LoadFont(..) + // or + // HelloImGui::LoadDpiResponsiveFont() // - // When loading fonts, use HelloImGui::LoadFont(fontFilename, fontSize, fontLoadingParams) + // Use these functions instead of ImGui::GetIO().Fonts->AddFontFromFileTTF(), + // because they will automatically adjust the font size to account for HighDPI, + // and will help you to get consistent font size across different OSes. + // // Font loading parameters: several options are available (color, merging, range, ...) struct FontLoadingParams @@ -101,14 +109,32 @@ See [hello_imgui_font.h](https://github.com/pthom/hello_imgui/blob/master/src/he ImFontConfig fontConfigFontAwesome = ImFontConfig(); }; - // When loading fonts, use HelloImGui::LoadFont(FontLoadingParams) - // =============================================================== - // instead of ImGui::GetIO().Fonts->AddFontFromFileTTF(), because it will - // automatically adjust the font size to account for HighDPI, and will spare - // you headaches when trying to get consistent font size across different OSes. - // see FontLoadingParams and ImFontConfig - ImFont* LoadFont(const std::string & fontFilename, float fontSize, - const FontLoadingParams & params = {}); + // A font that will be automatically resized to account for changes in DPI + // Use LoadAdaptiveFont instead of LoadFont to get this behavior. + // Fonts loaded with LoadAdaptiveFont will be reloaded during execution + // if ImGui::GetIO().FontGlobalScale is changed. + struct FontDpiResponsive + { + ImFont* font = nullptr; + std::string fontFilename; + float fontSize = 0.f; + FontLoadingParams fontLoadingParams; + }; + + + // Loads a font with the specified parameters + // (this font will not adapt to DPI changes after startup) + ImFont* LoadFont( + const std::string & fontFilename, float fontSize, + const FontLoadingParams & params = {}); + + // Loads a font with the specified parameters + // This font will adapt to DPI changes after startup. + // Only fonts loaded with LoadAdaptiveFont will adapt to DPI changes: + // avoid mixing LoadFont/LoadFontDpiResponsive) + FontDpiResponsive* LoadFontDpiResponsive( + const std::string & fontFilename, float fontSize, + const FontLoadingParams & params = {}); ``` @@ -266,6 +292,10 @@ ImGuiTestEngine* GetImGuiTestEngine(); // "Sdl - Vulkan" std::string GetBackendDescription(); +// `ChangeWindowSize(const ScreenSize &windowSize)`: sets the window size +// (useful if you want to change the window size during execution) +void ChangeWindowSize(const ScreenSize &windowSize); + ``` ---- @@ -408,42 +438,100 @@ void ShowAppMenu(RunnerParams & runnerParams); # Handling screens with high DPI -_Note: This part is relevant only for more advanced usages. If you use `HelloImGui::LoadFont()`, and always use `HelloImGui::EmToVec2()` to place widgets, you do not need to worry about DPI handling_ -## Details on DPI handling on different OS +_Note: This part is relevant only for more advanced usages. If you use `HelloImGui::LoadFont()`, + and always use `HelloImGui::EmToVec2()` to place widgets, you do not need to worry about DPI handling_ + +## OS specificities + +There are several important things to know about high-DPI handling within Hello ImGui and Dear ImGui: + +1. (virtual) screen coordinates vs (physical) pixels +2. DisplayFramebufferScale: Frame buffer size vs window size +3. FontGlobalScale: display-time font scaling factor +4. How to load fonts with the correct size +5. How to get similar window sizes on different OSes/DPI + + +## Screen coordinates + +Screen coordinates are the coordinates you use to place and size windows on the screen. + +**Screen coordinates do not always correspond to physical pixels** + +- On macOS/iOS retina screens, a screen coordinate corresponds typically + to 2x2 physical pixels (but this may vary if you change the display scaling) +- On most Linux distributions, whenever there is a high DPI screen + you can set the display scale. For example if you set the scale to 300%, + then a screen coordinate will correspond to 3x3 physical pixels +- On Windows, there are two possible situations: + - If the application is DPI aware, a screen coordinate corresponds to 1x1 physical pixel, + and you can use the full extent of your screen resolution. + - If the application is not DPI aware, a screen coordinate may correspond to 2x2 physical pixels + (if the display scaling is set to 200% for example). However, the rendering of your application + will be blurry and will not use the full extent of your screen resolution. + - Notes: + - Applications created with HelloImGui are DPI aware by default (when using glfw and sdl backends). + - SDL applications are normally not DPI aware. However, HelloImGui makes them DPI aware. + + +## DisplayFramebufferScale +`DisplayFramebufferScale` is the ratio between the frame buffer size and the window size. + +The frame buffer size is the size of the internal buffer used by the rendering backend. +It might be bigger than the actual window size. +`ImVec2 ImGui::GetIO().DisplayFramebufferScale` is a factor by which the frame buffer size is bigger than the window size. +It is set by the platform backend after it was initialized, and typically reflects the scaling ratio between +physical pixels and screen coordinates. + +Under windows, it will always be (1,1). Under macOS / linux, it will reflect the current display scaling. +It will typically be (2,2) on a macOS retina screen. + +Notes: +- You cannot change DisplayFramebufferScale manually, it will be reset at each new frame, by asking the platform backend. + + +## FontGlobalScale + +`ImGui::GetIO().FontGlobalScale` is a factor by which fonts glyphs should be scaled at rendering time. +It is typically 1 on windows, and 0.5 on macOS retina screens. -Let's consider screen whose physical pixel resolution is 3600x2000, but which will displayed with a scaling factor of 200%, so that widgets do not look too small on it. -The way it is handled depends on the OS: -- On MacOS, the screen will be seen as having a resolution of 1800x1000, and the OS handles the resizing by itself. -- On Linux, and on Windows if the application is DPI aware, the screen will be seen as having a resolution of 3600x2000. -- On Windows if the application is not DPI aware, the screen will be seen as having a resolution of 1800x1000 +## How to load fonts with the correct size -By default, if using the glfw backend, applications will be Dpi aware under windows. -Sdl applications are normally not Dpi aware. However HelloImGui makes them Dpi aware when using the sdl backend. +### Using HelloImGui (recommended) +[`HelloImGui::LoadFont()` and `HelloImGui::LoadFontDpiResponsive`](https://pthom.github.io/hello_imgui/book/doc_api.html#load-fonts) will load fonts + with the correct size, taking into account the DPI scaling. -## Dpi aware Font scaling +### Using Dear ImGui +`ImGui::GetIO().Fonts->AddFontFromFileTTF()` loads a font with a given size, in *physical pixels*. -`HelloImGui::LoadFont()` will load fonts with the correct size, taking into account the DPI scaling. +If for example, DisplayFramebufferScale is (2,2), and you load a font with a size of 16, it will by default be rendered + with size of 16 *virtual screen coordinate pixels* (i.e. 32 physical pixels). This will lead to blurry text. +To solve this, you should load your font with a size of 16 *virtual screen coordinate pixels* (i.e. 32 physical pixels), +and set `ImGui::GetIO().FontGlobalScale` to 0.5. -If you prefer to use `ImGui::GetIO().Fonts->AddFontFromFileTTF()`, there are two things to know: +Helpers if using `ImGui::GetIO().Fonts->AddFontFromFileTTF()`: +- `HelloImGui::ImGuiDefaultFontGlobalScale()` returns the default value that should be stored inside `ImGui::GetIO().FontGlobalScale`. +- `HelloImGui::DpiFontLoadingFactor()` returns a factor by which you shall multiply your font sizes when loading them. -1. You should adjust `ImGui::GetIO().FontGlobalScale`: -Under windows and linux, it should be is 1: no rescaling should be done by ImGui. -Under macOS and emscripten, it may need to bet set to 0.5 (for example it will be 0.5 if the dpi scaling is 200% -on a macOS retina screen) +## Reproducible physical window sizes (in mm or inches) -`HelloImGui::ImGuiDefaultFontGlobalScale()` returns the default value that should be stored inside `ImGui::GetIO().FontGlobalScale`. +### Using HelloImGui +Simply specify a window size that corresponds to theoretical 96 PPI screen (inside `RunnerParams.appWindowParams.windowGeometry.size`) +### Using your own code to create the backend window +If you prefer to create the window by yourself, its physical size in millimeters may vary widely, +depending on the OS and the current screen DPI setting. +Typically under Windows, your window may appear to be very small if your screen is high DPI. -2. You should adjust the font size when loading a font: +To get a similar window size on different OSes/DPI, you should multiply the window size by `HelloImGui::DpiWindowSizeFactor()`. -`HelloImGui::DpiFontLoadingFactor()` returns a factor by which you shall multiply your font sizes when loading them. +Note: DpiWindowSizeFactor() is equal to `CurrentScreenPixelPerInch / 96` under windows and linux, and always 1 under macOS. -`HelloImGui::DpiFontLoadingFactor()` corresponds to: -`DpiWindowSizeFactor() * 1.f / ImGui::GetIO().FontGlobalScale` +## Fine tune DPI Handling -where DpiWindowSizeFactor() is equal to `CurrentScreenPixelPerInch / 96` -under windows and linux, 1 under macOS +See [`HelloImGui::DpiAwareParams`](https://pthom.github.io/hello_imgui/book/doc_params.html#dpi-aware-params) +for more information on how to fine tune DPI handling when using Hello ImGui. diff --git a/docs/book/_sources/doc_params.md b/docs/book/_sources/doc_params.md index c89c4669..d93376ff 100644 --- a/docs/book/_sources/doc_params.md +++ b/docs/book/_sources/doc_params.md @@ -1,6 +1,27 @@ # Application parameters -_RunnerParams_ contains all the settings and callbacks in order to run an application. + +__HelloImGui::Run()__ will run an application with a single call. + +Three signatures are provided: + +* `HelloImGui::Run(RunnerParams &)`: full signature, the most customizable version. + Runs an application whose params and Gui are provided by runnerParams. + +* `HelloImGui::Run(const SimpleRunnerParams&)`: + Runs an application, using simpler params. + +* `HelloImGui::Run(guiFunction, windowTitle, windowSize, windowSizeAuto=false, restoreLastWindowGeometry=false, fpsIdle=10)` + Runs an application, by providing the Gui function, the window title, etc. + +Although the API is extremely simple, it is highly customizable, and you can set many options by filling +the elements in the `RunnerParams` struct, or in the simpler `SimpleRunnerParams`. + +__HelloImGui::GetRunnerParams()__ will return the runnerParams of the current application. + + +# Diagram + The diagram below summarize all the possible settings and callbacks (which are explained in detail later in this document). [![diagram](https://raw.githubusercontent.com/pthom/hello_imgui/master/src/hello_imgui/doc_src/hello_imgui_diagram.jpg)](https://raw.githubusercontent.com/pthom/hello_imgui/master/src/hello_imgui/doc_src/hello_imgui_diagram.jpg) @@ -49,6 +70,8 @@ struct SimpleRunnerParams // `windowSize`: _ScreenSize, default={800, 600}_. // Size of the window + // The size will be handled as if it was specified for a 96PPI screen + // (i.e. a given size will correspond to the same physical size on different screens, whatever their DPI) ScreenSize windowSize = DefaultWindowSize; // `fpsIdle`: _float, default=9_. @@ -131,7 +154,6 @@ struct RunnerParams RendererBackendType rendererBackendType = RendererBackendType::FirstAvailable; - // --------------- Settings ------------------- // `iniFolderType`: _IniFolderType, default = IniFolderType::CurrentFolder_ @@ -194,6 +216,9 @@ struct RunnerParams // Set the application refresh rate // (only used on emscripten: 0 stands for "let the app or the browser decide") int emscripten_fps = 0; + + // Parameters for Remote display (experimental, unsupported) + RemoteParams remoteParams; }; ``` @@ -212,6 +237,7 @@ enum class PlatformBackendType FirstAvailable, Glfw, Sdl, + Null }; // Rendering backend type (OpenGL3, Metal, Vulkan, DirectX11, DirectX12) @@ -224,6 +250,7 @@ enum class RendererBackendType Vulkan, DirectX11, DirectX12, + Null }; ``` @@ -313,11 +340,10 @@ struct RunnerCallbacks void EnqueuePostInit(const VoidFunction& callback); // `LoadAdditionalFonts`: default=_LoadDefaultFont_WithFontAwesome*. - // A function that is called once, when fonts are ready to be loaded. - // By default, _LoadDefaultFont_WithFontAwesome_ is called, - // but you can copy and customize it. - // (LoadDefaultFont_WithFontAwesome will load fonts from assets/fonts/ - // but reverts to the ImGui embedded font if not found) + // A function that is called in order to load fonts. + // `LoadAdditionalFonts` will be called once, then *set to nullptr*. + // If you want to load additional fonts, during the app execution, you can + // set LoadAdditionalFonts to a function that will load the additional fonts. VoidFunction LoadAdditionalFonts = (VoidFunction)ImGuiDefaultSettings::LoadDefaultFont_WithFontAwesomeIcons; // If LoadAdditionalFonts==LoadDefaultFont_WithFontAwesomeIcons, this parameter control // which icon font will be loaded by default. @@ -361,7 +387,7 @@ struct RunnerCallbacks // `PreNewFrame`: You can here add a function that will be called at each frame, // and before the call to ImGui::NewFrame(). - // It is a good place to dynamically add new fonts, or new dockable windows. + // It is a good place to add new dockable windows. VoidFunction PreNewFrame = EmptyVoidFunction(); // `BeforeImGuiRender`: You can here add a function that will be called at each frame, @@ -581,6 +607,8 @@ struct WindowGeometry // Size of the application window // used if fullScreenMode==NoFullScreen and sizeAuto==false. Default=(800, 600) + // The size will be handled as if it was specified for a 96PPI screen + // (i.e. a given size will correspond to the same physical size on different screens, whatever their DPI) ScreenSize size = DefaultWindowSize; // If sizeAuto=true, adapt the app window size to the presented widgets. @@ -821,8 +849,9 @@ struct FpsIdling # Dpi Aware Params -See [dpi_aware.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/dpi_aware.h) +Optionally, DPI parameters can be fine-tuned. For detailed info, see [handling screens with high dpi](https://pthom.github.io/hello_imgui/book/doc_api.html#handling-screens-with-high-dpi) +Source: [dpi_aware.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/dpi_aware.h) ```cpp // @@ -855,11 +884,15 @@ See [dpi_aware.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_img // dpiWindowSizeFactor=2 // fontRenderingScale=0.5 // +// For more information, see the documentation on DPI handling, here: https://pthom.github.io/hello_imgui/book/doc_api.html#handling-screens-with-high-dpi +// struct DpiAwareParams { // `dpiWindowSizeFactor` - // factor by which window size should be multiplied to get a similar - // visible size on different OSes. + // factor by which window size should be multiplied to get a similar + // physical size on different OSes (as if they were all displayed on a 96 PPI screen). + // This affects the size of native app windows, + // but *not* imgui Windows, and *not* the size of widgets and text. // In a standard environment (i.e. outside of Hello ImGui), an application with a size of 960x480 pixels, // may have a physical size (in mm or inches) that varies depending on the screen DPI, and the OS. // @@ -874,23 +907,36 @@ struct DpiAwareParams float dpiWindowSizeFactor = 0.0f; // `fontRenderingScale` - // factor (that is either 1 or < 1.) by which fonts glyphs should be - // scaled at rendering time. - // On macOS retina screens, it will be 0.5, since macOS APIs hide - // the real resolution of the screen. + // factor (that is either 1 or < 1.) by which fonts glyphs should be scaled at rendering time. + // On macOS retina screens, it will be 0.5, since macOS APIs hide the real resolution of the screen. + // Changing this value will *not* change the visible font size on the screen, however it will + // affect the size of the loaded glyphs. + // For example, if fontRenderingScale=0.5 (which is the default on a macOS retina screen), + // a font size of 16 will be loaded as if it was 32, and will be rendered at half size. + // This leads to a better rendering quality on some platforms. + // (This parameter will be used to set ImGui::GetIO().FontGlobalScale at startup) float fontRenderingScale = 0.0f; + // `onlyUseFontDpiResponsive` + // If true, guarantees that only HelloImGui::LoadDpiResponsiveFont will be used to load fonts. + // (also for the default font) + bool onlyUseFontDpiResponsive = false; + // `dpiFontLoadingFactor` - // factor by which font size should be multiplied at loading time to get a similar - // visible size on different OSes. - // The size will be equivalent to a size given for a 96 PPI screen - float DpiFontLoadingFactor() { return dpiWindowSizeFactor / fontRenderingScale;}; + // factor by which font size should be multiplied at loading time to get a similar + // visible size on different OSes. + // The size will be equivalent to a size given for a 96 PPI screen + float DpiFontLoadingFactor() const { + float r = dpiWindowSizeFactor / fontRenderingScale; + return r; + }; }; // ---------------------------------------------------------------------------- ``` + ---- # Docking diff --git a/docs/book/build.html b/docs/book/build.html index d6c48a65..34e585f9 100644 --- a/docs/book/build.html +++ b/docs/book/build.html @@ -69,7 +69,7 @@ - + @@ -186,7 +186,7 @@ @@ -484,8 +498,15 @@

Place widgets in a DPI-aware way

Load fonts#

See hello_imgui_font.h.

-
    //
-    // When loading fonts, use HelloImGui::LoadFont(fontFilename, fontSize, fontLoadingParams)
+
    // When loading fonts, use
+    //          HelloImGui::LoadFont(..)
+    //      or
+    //      	HelloImGui::LoadDpiResponsiveFont()
+    //
+    // Use these functions instead of ImGui::GetIO().Fonts->AddFontFromFileTTF(),
+    // because they will automatically adjust the font size to account for HighDPI,
+    // and will help you to get consistent font size across different OSes.
+
     //
     // Font loading parameters: several options are available (color, merging, range, ...)
     struct FontLoadingParams
@@ -528,14 +549,32 @@ 
Load fonts        ImFontConfig fontConfigFontAwesome = ImFontConfig();
     };
 
-    // When loading fonts, use HelloImGui::LoadFont(FontLoadingParams)
-    // ===============================================================
-    // instead of ImGui::GetIO().Fonts->AddFontFromFileTTF(), because it will
-    // automatically adjust the font size to account for HighDPI, and will spare
-    // you headaches when trying to get consistent font size across different OSes.
-    // see FontLoadingParams and ImFontConfig
-    ImFont* LoadFont(const std::string & fontFilename, float fontSize,
-                     const FontLoadingParams & params = {});
+    // A font that will be automatically resized to account for changes in DPI
+    // Use LoadAdaptiveFont instead of LoadFont to get this behavior.
+    // Fonts loaded with LoadAdaptiveFont will be reloaded during execution
+    // if ImGui::GetIO().FontGlobalScale is changed.
+    struct FontDpiResponsive
+    {
+        ImFont* font = nullptr;
+        std::string fontFilename;
+        float fontSize = 0.f;
+        FontLoadingParams fontLoadingParams;
+    };
+
+
+    // Loads a font with the specified parameters
+    // (this font will not adapt to DPI changes after startup)
+    ImFont* LoadFont(
+        const std::string & fontFilename, float fontSize,
+        const FontLoadingParams & params = {});
+
+    // Loads a font with the specified parameters
+    // This font will adapt to DPI changes after startup.
+    // Only fonts loaded with LoadAdaptiveFont will adapt to DPI changes:
+    // avoid mixing LoadFont/LoadFontDpiResponsive)
+    FontDpiResponsive* LoadFontDpiResponsive(
+        const std::string & fontFilename, float fontSize,
+        const FontLoadingParams & params = {});
 

 

 
@@ -683,6 +722,10 @@ 
Utility functions//     "Glfw - Metal"
 //     "Sdl - Vulkan"
 std::string GetBackendDescription();
+
+// `ChangeWindowSize(const ScreenSize &windowSize)`: sets the window size
+// (useful if you want to change the window size during execution)
+void ChangeWindowSize(const ScreenSize &windowSize);
@@ -813,38 +856,106 @@

Customize Hello ImGui Menus

Handling screens with high DPI#

-

Note: This part is relevant only for more advanced usages. If you use HelloImGui::LoadFont(), and always use HelloImGui::EmToVec2() to place widgets, you do not need to worry about DPI handling

-
-

Details on DPI handling on different OS#

-

Let’s consider screen whose physical pixel resolution is 3600x2000, but which will displayed with a scaling factor of 200%, so that widgets do not look too small on it.

-

The way it is handled depends on the OS:

+

Note: This part is relevant only for more advanced usages. If you use HelloImGui::LoadFont(), +and always use HelloImGui::EmToVec2() to place widgets, you do not need to worry about DPI handling

+
+

OS specificities#

+

There are several important things to know about high-DPI handling within Hello ImGui and Dear ImGui:

+
    +

  1. (virtual) screen coordinates vs (physical) pixels

    2. +

  2. DisplayFramebufferScale: Frame buffer size vs window size

    3. +

  3. FontGlobalScale: display-time font scaling factor

    4. +

  4. How to load fonts with the correct size

    5. +

  5. How to get similar window sizes on different OSes/DPI

    6. +
+
+
+

Screen coordinates#

+

Screen coordinates are the coordinates you use to place and size windows on the screen.

+

Screen coordinates do not always correspond to physical pixels

    -

  • On MacOS, the screen will be seen as having a resolution of 1800x1000, and the OS handles the resizing by itself.

    • -

  • On Linux, and on Windows if the application is DPI aware, the screen will be seen as having a resolution of 3600x2000.

    • -

  • On Windows if the application is not DPI aware, the screen will be seen as having a resolution of 1800x1000

    • +

  • On macOS/iOS retina screens, a screen coordinate corresponds typically +to 2x2 physical pixels (but this may vary if you change the display scaling)

    • +

  • On most Linux distributions, whenever there is a high DPI screen +you can set the display scale. For example if you set the scale to 300%, +then a screen coordinate will correspond to 3x3 physical pixels

    • +

  • On Windows, there are two possible situations:

    +
      +

    • If the application is DPI aware, a screen coordinate corresponds to 1x1 physical pixel, +and you can use the full extent of your screen resolution.

      • +

    • If the application is not DPI aware, a screen coordinate may correspond to 2x2 physical pixels +(if the display scaling is set to 200% for example). However, the rendering of your application +will be blurry and will not use the full extent of your screen resolution.

      • +

    • Notes:

      +
        +

      • Applications created with HelloImGui are DPI aware by default (when using glfw and sdl backends).

        • +

      • SDL applications are normally not DPI aware. However, HelloImGui makes them DPI aware.

        • +
      +
      • +
    +
-

By default, if using the glfw backend, applications will be Dpi aware under windows. -Sdl applications are normally not Dpi aware. However HelloImGui makes them Dpi aware when using the sdl backend.

-
-

Dpi aware Font scaling#

-

HelloImGui::LoadFont() will load fonts with the correct size, taking into account the DPI scaling.

-

If you prefer to use ImGui::GetIO().Fonts->AddFontFromFileTTF(), there are two things to know:

-
    -

  1. You should adjust ImGui::GetIO().FontGlobalScale:

    2. -
-

Under windows and linux, it should be is 1: no rescaling should be done by ImGui. -Under macOS and emscripten, it may need to bet set to 0.5 (for example it will be 0.5 if the dpi scaling is 200% -on a macOS retina screen)

-

HelloImGui::ImGuiDefaultFontGlobalScale() returns the default value that should be stored inside ImGui::GetIO().FontGlobalScale.

-
    -

  1. You should adjust the font size when loading a font:

    2. -
-

HelloImGui::DpiFontLoadingFactor() returns a factor by which you shall multiply your font sizes when loading them.

-

HelloImGui::DpiFontLoadingFactor() corresponds to: -DpiWindowSizeFactor() * 1.f / ImGui::GetIO().FontGlobalScale

-

where DpiWindowSizeFactor() is equal to CurrentScreenPixelPerInch / 96 -under windows and linux, 1 under macOS

+
+

DisplayFramebufferScale#

+

DisplayFramebufferScale is the ratio between the frame buffer size and the window size.

+

The frame buffer size is the size of the internal buffer used by the rendering backend. +It might be bigger than the actual window size. +ImVec2 ImGui::GetIO().DisplayFramebufferScale is a factor by which the frame buffer size is bigger than the window size. +It is set by the platform backend after it was initialized, and typically reflects the scaling ratio between +physical pixels and screen coordinates.

+

Under windows, it will always be (1,1). Under macOS / linux, it will reflect the current display scaling. +It will typically be (2,2) on a macOS retina screen.

+

Notes:

+
    +

  • You cannot change DisplayFramebufferScale manually, it will be reset at each new frame, by asking the platform backend.

    • +
+
+
+

FontGlobalScale#

+

ImGui::GetIO().FontGlobalScale is a factor by which fonts glyphs should be scaled at rendering time. +It is typically 1 on windows, and 0.5 on macOS retina screens.

+
+
+

How to load fonts with the correct size#

+ +
+

Using Dear ImGui#

+

ImGui::GetIO().Fonts->AddFontFromFileTTF() loads a font with a given size, in physical pixels.

+

If for example, DisplayFramebufferScale is (2,2), and you load a font with a size of 16, it will by default be rendered +with size of 16 virtual screen coordinate pixels (i.e. 32 physical pixels). This will lead to blurry text. +To solve this, you should load your font with a size of 16 virtual screen coordinate pixels (i.e. 32 physical pixels), +and set ImGui::GetIO().FontGlobalScale to 0.5.

+

Helpers if using ImGui::GetIO().Fonts->AddFontFromFileTTF():

+
    +

  • HelloImGui::ImGuiDefaultFontGlobalScale() returns the default value that should be stored inside ImGui::GetIO().FontGlobalScale.

    • +

  • HelloImGui::DpiFontLoadingFactor() returns a factor by which you shall multiply your font sizes when loading them.

    • +
+
+
+
+

Reproducible physical window sizes (in mm or inches)#

+
+

Using HelloImGui#

+

Simply specify a window size that corresponds to theoretical 96 PPI screen (inside RunnerParams.appWindowParams.windowGeometry.size)

+
+
+

Using your own code to create the backend window#

+

If you prefer to create the window by yourself, its physical size in millimeters may vary widely, +depending on the OS and the current screen DPI setting. +Typically under Windows, your window may appear to be very small if your screen is high DPI.

+

To get a similar window size on different OSes/DPI, you should multiply the window size by HelloImGui::DpiWindowSizeFactor().

+

Note: DpiWindowSizeFactor() is equal to CurrentScreenPixelPerInch / 96 under windows and linux, and always 1 under macOS.

+
+
+
+

Fine tune DPI Handling#

+

See HelloImGui::DpiAwareParams +for more information on how to fine tune DPI handling when using Hello ImGui.

@@ -879,20 +990,20 @@

Dpi aware Font scaling

previous

-

Get started

+

Application parameters

next

-

Application parameters

+

Build instructions

 @@ -931,8 +1042,21 @@

Dpi aware Font scaling
  • Customize Hello ImGui Menus
  • Handling screens with high DPI
    • diff --git a/docs/book/doc_params.html b/docs/book/doc_params.html index 1ca855f6..222ee6a9 100644 --- a/docs/book/doc_params.html +++ b/docs/book/doc_params.html @@ -69,8 +69,8 @@ - - + + @@ -187,7 +187,7 @@
    • Get started
      • -
    • API
      • +
    • Application parameters
      • @@ -197,7 +197,8 @@ -
    • Application parameters
      • +
    • API
      • + @@ -403,6 +404,7 @@

      Contents