Skip to content

Commit

Permalink
Add DpiAwareParams
Browse files Browse the repository at this point in the history
  • Loading branch information
@pthom
pthom committed Feb 5, 2024
1 parent 3ed6823 commit 4adb78c
Show file tree
Hide file tree
Showing 8 changed files with 393 additions and 112 deletions.
8 changes: 8 additions & 0 deletions src/hello_imgui/doc_api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -278,6 +278,14 @@ float FrameRate(float durationForMean = 0.5f);
// of ImGuiTestEngine that was initialized by HelloImGui
// (iif ImGui Test Engine is active).
ImGuiTestEngine* GetImGuiTestEngine();
// `GetBackendDescription()`: returns a string with the backend info
// Could be for example:
// "Glfw - OpenGL3"
// "Glfw - Metal"
// "Sdl - Vulkan"
std::string GetBackendDescription();
```

----
Expand Down
169 changes: 127 additions & 42 deletions src/hello_imgui/doc_params.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,13 +56,17 @@ struct SimpleRunnerParams
float fpsIdle = 9.f;

// `enableIdling`: _bool, default=true_.
// Set this to false to disable idling at startup
// Disable idling at startup by setting this to false
// When running, use:
// HelloImGui::GetRunnerParams()->fpsIdling.enableIdling = false;
bool enableIdling = true;

RunnerParams ToRunnerParams() const;
};
```

---

## Full params

```cpp
Expand Down Expand Up @@ -114,9 +118,10 @@ struct RunnerParams
// Select the wanted platform backend type between `Sdl`, `Glfw`.
// if `FirstAvailable`, Glfw will be preferred over Sdl when both are available.
// Only useful when multiple backend are compiled and available.
PlatformBackendType backendType = PlatformBackendType::FirstAvailable;
// (for compatibility with older versions, you can use BackendType instead of PlatformBackendType)
PlatformBackendType platformBackendType = PlatformBackendType::FirstAvailable;

// `rendererBackendType`: _enum RendererBackendType, default=RendererBackendType::FirstAvailable_
// `renderingBackendType`: _enum RenderingBackendType, default=RenderingBackendType::FirstAvailable_
// Select the wanted rendering backend type between `OpenGL3`, `Metal`, `Vulkan`, `DirectX11`, `DirectX12`.
// if `FirstAvailable`, it will be selected in the order of preference mentioned above.
// Only useful when multiple rendering backend are compiled and available.
Expand Down Expand Up @@ -166,6 +171,8 @@ struct RunnerParams
// (set fpsIdling.enableIdling to false to disable Idling)
FpsIdling fpsIdling;

// --------------- DPI Handling -----------
DpiAwareParams dpiAwareParams;

// --------------- Misc -------------------

Expand All @@ -185,6 +192,11 @@ 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;

// --------------- Legacy -------------------`
#ifndef HELLOIMGUI_DISABLE_OBSOLETE_BACKEND
PlatformBackendType& backendType = platformBackendType; // a synonym, for backward compatibility
#endif
};
```

Expand All @@ -194,7 +206,7 @@ struct RunnerParams
```cpp

// You can select the platform backend type (SDL, GLFW) and the rendering backend type
// via RunnerParams.backendType and RunnerParams.rendererBackendType.
// via RunnerParams.backendType and RunnerParams.renderingBackendType.

// Platform backend type (SDL, GLFW)
// They are listed in the order of preference when FirstAvailable is selected.
Expand All @@ -205,7 +217,9 @@ enum class PlatformBackendType
Sdl,
};

#ifndef HELLOIMGUI_DISABLE_OBSOLETE_BACKEND
using BackendType = PlatformBackendType; // for backward compatibility
#endif

// Rendering backend type (OpenGL3, Metal, Vulkan, DirectX11, DirectX12)
// They are listed in the order of preference when FirstAvailable is selected.
Expand All @@ -222,44 +236,6 @@ enum class RendererBackendType
```


# Fps Idling

See [runner_params.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_params.h).

```cpp

// FpsIdling is a struct that contains Fps Idling parameters
struct FpsIdling
{
// `fpsIdle`: _float, default=9_.
// ImGui applications can consume a lot of CPU, since they update the screen
// very frequently. In order to reduce the CPU usage, the FPS is reduced when
// no user interaction is detected.
// This is ok most of the time but if you are displaying animated widgets
// (for example a live video), you may want to ask for a faster refresh:
// either increase fpsIdle, or set it to 0 for maximum refresh speed
// (you can change this value during the execution depending on your application
// refresh needs)
float fpsIdle = 9.f;

// `enableIdling`: _bool, default=true_.
// Disable idling by setting this to false.
// (this can be changed dynamically during execution)
bool enableIdling = true;

// `isIdling`: bool (dynamically updated during execution)
// This bool will be updated during the application execution,
// and will be set to true when it is idling.
bool isIdling = false;

// `rememberEnableIdling`: _bool, default=true_.
// If true, the last value of enableIdling is restored from the settings at startup.
bool rememberEnableIdling = false;
};
```

----

# Runner callbacks

See [runner_callbacks.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_callbacks.h).
Expand Down Expand Up @@ -812,6 +788,115 @@ enum class DefaultImGuiWindowType
};
```

# Fps Idling

See [runner_params.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_params.h).

```cpp

// FpsIdling is a struct that contains Fps Idling parameters
struct FpsIdling
{
// `fpsIdle`: _float, default=9_.
// ImGui applications can consume a lot of CPU, since they update the screen
// very frequently. In order to reduce the CPU usage, the FPS is reduced when
// no user interaction is detected.
// This is ok most of the time but if you are displaying animated widgets
// (for example a live video), you may want to ask for a faster refresh:
// either increase fpsIdle, or set it to 0 for maximum refresh speed
// (you can change this value during the execution depending on your application
// refresh needs)
float fpsIdle = 9.f;

// `enableIdling`: _bool, default=true_.
// Disable idling by setting this to false.
// (this can be changed dynamically during execution)
bool enableIdling = true;

// `isIdling`: bool (dynamically updated during execution)
// This bool will be updated during the application execution,
// and will be set to true when it is idling.
bool isIdling = false;

// `rememberEnableIdling`: _bool, default=true_.
// If true, the last value of enableIdling is restored from the settings at startup.
bool rememberEnableIdling = false;
};
```

# Dpi Aware Params

See [dpi_aware.h](ttps://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/dpi_aware.h)

```cpp

//
// Hello ImGui will try its best to automatically handle DPI scaling for you.
// It does this by setting two values:
//
// - `dpiWindowSizeFactor`:
// factor by which window size should be multiplied
//
// - `fontRenderingScale`:
// factor by which fonts glyphs should be scaled at rendering time
// (typically 1 on windows, and 0.5 on macOS retina screens)
//
// By default, Hello ImGui will compute them automatically,
// when dpiWindowSizeFactor and fontRenderingScale are set to 0.
//
// How to set those values manually:
// ---------------------------------
// If it fails (i.e. your window and/or fonts are too big or too small),
// you may set them manually:
// (1) Either by setting them programmatically in your application
// (set their values in `runnerParams.dpiAwareParams`)
// (2) Either by setting them in the app ini file
// (3) Either by setting them in a `hello_imgui.ini` file in the app folder, or any of its parent folders.
// (this is useful when you want to set them for a specific app or set of apps, without modifying the app code)
// Note: if several methods are used, the order of priority is (1) > (2) > (3)
//
// Example content of a ini file:
// ------------------------------
// [DpiAwareParams]
// dpiWindowSizeFactor=2
// fontRenderingScale=0.5
//
struct DpiAwareParams
{
// `dpiWindowSizeFactor`
// factor by which window size should be multiplied to get a similar
// visible size on different OSes.
// 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.
//
// Inside Hello ImGui, the window size is always treated as targeting a 96 PPI screen, so that its size will
// look similar whatever the OS and the screen DPI.
// In our example, our 960x480 pixels window will try to correspond to a 10x5 inches window
//
// Hello ImGui does its best to compute it on all OSes.
// However, if it fails you may set its value manually.
// If it is set to 0, Hello ImGui will compute it automatically,
// and the resulting value will be stored in `dpiWindowSizeFactor`.
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.
float fontRenderingScale = 0.0f;

// `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;};
};

// ----------------------------------------------------------------------------

```

----

# Docking
Expand Down
28 changes: 18 additions & 10 deletions src/hello_imgui/doc_params.src.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ See [runner_params.h](https://github.com/pthom/hello_imgui/blob/master/src/hello
@import "runner_params.h" {md_id=SimpleRunnerParams}
```
---
## Full params
```cpp
Expand All @@ -30,16 +32,6 @@ See [runner_params.h](https://github.com/pthom/hello_imgui/blob/master/src/hello
```
# Fps Idling
See [runner_params.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_params.h).
```cpp
@import "runner_params.h" {md_id=FpsIdling}
```

----

# Runner callbacks
See [runner_callbacks.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_callbacks.h).
Expand Down Expand Up @@ -118,6 +110,22 @@ See [imgui_window_params.h](https://github.com/pthom/hello_imgui/blob/master/src
@import "imgui_window_params.h" {md_id=DefaultImGuiWindowType}
```

# Fps Idling

See [runner_params.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_params.h).

```cpp
@import "runner_params.h" {md_id=FpsIdling}
```
# Dpi Aware Params
See [dpi_aware.h](ttps://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/dpi_aware.h)
```cpp
@import "dpi_aware.h" {md_id=DpiAwareParams}
```

----

# Docking
Expand Down
74 changes: 74 additions & 0 deletions src/hello_imgui/dpi_aware.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,75 @@

namespace HelloImGui
{
// @@md#DpiAwareParams

//
// Hello ImGui will try its best to automatically handle DPI scaling for you.
// It does this by setting two values:
//
// - `dpiWindowSizeFactor`:
// factor by which window size should be multiplied
//
// - `fontRenderingScale`:
// factor by which fonts glyphs should be scaled at rendering time
// (typically 1 on windows, and 0.5 on macOS retina screens)
//
// By default, Hello ImGui will compute them automatically,
// when dpiWindowSizeFactor and fontRenderingScale are set to 0.
//
// How to set those values manually:
// ---------------------------------
// If it fails (i.e. your window and/or fonts are too big or too small),
// you may set them manually:
// (1) Either by setting them programmatically in your application
// (set their values in `runnerParams.dpiAwareParams`)
// (2) Either by setting them in the app ini file
// (3) Either by setting them in a `hello_imgui.ini` file in the current folder, or any of its parent folders.
// (this is useful when you want to set them for a specific app or set of apps, without modifying the app code)
// Note: if several methods are used, the order of priority is (1) > (2) > (3)
//
// Example content of a ini file:
// ------------------------------
// [DpiAwareParams]
// dpiWindowSizeFactor=2
// fontRenderingScale=0.5
//
struct DpiAwareParams
{
// `dpiWindowSizeFactor`
// factor by which window size should be multiplied to get a similar
// visible size on different OSes.
// 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.
//
// Inside Hello ImGui, the window size is always treated as targeting a 96 PPI screen, so that its size will
// look similar whatever the OS and the screen DPI.
// In our example, our 960x480 pixels window will try to correspond to a 10x5 inches window
//
// Hello ImGui does its best to compute it on all OSes.
// However, if it fails you may set its value manually.
// If it is set to 0, Hello ImGui will compute it automatically,
// and the resulting value will be stored in `dpiWindowSizeFactor`.
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.
float fontRenderingScale = 0.0f;

// `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;};
};

// ----------------------------------------------------------------------------

// @@md

/**
@@md#DocEmToVec2
Expand Down Expand Up @@ -35,6 +104,11 @@ float EmSize(float nbLines);
} // namespace HelloImGui


// ----------------------------------------------------------------------------

//
// Legacy API, you should use RunnerParams.dpAwareParams instead
//
namespace HelloImGui
{
// Multiply font sizes by this factor when loading fonts manually with ImGui::GetIO().Fonts->AddFont...
Expand Down
Loading

0 comments on commit 4adb78c

Please sign in to comment.