Skip to content

Commit

Permalink
Update docs / 2024-10-10 / 18:27:21
Browse files Browse the repository at this point in the history
  • Loading branch information
@pthom
pthom committed Oct 10, 2024
1 parent c318754 commit 52e4b37
Show file tree
Hide file tree
Showing 10 changed files with 217 additions and 3 deletions.
83 changes: 83 additions & 0 deletions docs/book/_sources/doc_api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,83 @@ the elements in the `RunnerParams` struct, or in the simpler `SimpleRunnerParam
__HelloImGui::GetRunnerParams()__ will return the runnerParams of the current application.


# Run Application while handling the rendering loop
If you want to be in control of the rendering loop, you may use the namespace `HelloImGui::ManualRender` (available since September 2024)

```cpp

namespace ManualRender
{
// HelloImGui::ManualRender is a namespace that groups functions, allowing fine-grained control over the rendering process:
// - It is customizable like HelloImGui::Run: initialize it with `RunnerParams` or `SimpleRunnerParams`
// - `ManualRender::Render()` will render the application for one frame:
// - Ensure that `ManualRender::Render()` is triggered regularly (e.g., through a loop or other mechanism)
// to maintain responsiveness. This method must be called on the main thread.
//
// A typical use case is:
// C++
// ```cpp
// HelloImGui::RunnerParams runnerParams;
// runnerParams.callbacks.ShowGui = ...; // your GUI function
// // Optionally, choose between Sleep, EarlyReturn, or Auto for fps idling mode:
// // runnerParams.fpsIdling.fpsIdlingMode = HelloImGui::FpsIdlingMode::Sleep; // or EarlyReturn, Auto
// HelloImGui::ManualRender::SetupFromRunnerParams(runnerParams);
// while (!HelloImGui::GetRunnerParams()->appShallExit)
// {
// HelloImGui::ManualRender::Render();
// }
// HelloImGui::ManualRender::TearDown();
// ```
// Python:
// ```python
// runnerParams = HelloImGui.RunnerParams()
// runnerParams.callbacks.show_gui = ... # your GUI function
// while not hello_imgui.get_runner_params().app_shall_exit:
// hello_imgui.manual_render.render()
// hello_imgui.manual_render.tear_down()
// ```
//
// **Notes:**
// 1. Depending on the configuration (`runnerParams.fpsIdling.fpsIdlingMode`), `HelloImGui` may enter
// an idle state to reduce CPU usage, if no events are received (e.g., no input or interaction).
// In this case, `Render()` will either sleep or return immediately.
// By default,
// - On Emscripten, `ManualRender::Render()` will return immediately to avoid blocking the main thread.
// - On other platforms, it will sleep
// 2. If initialized with `RunnerParams`, a copy of the `RunnerParams` will be made
// (which can be accessed with `HelloImGui::GetRunnerParams()`).

// Initializes the rendering with the full customizable `RunnerParams`.
// This will initialize the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).
// A distinct copy of `RunnerParams` is stored internally.
void SetupFromRunnerParams(const RunnerParams& runnerParams);

// Initializes the rendering with `SimpleRunnerParams`.
// This will initialize the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).
void SetupFromSimpleRunnerParams(const SimpleRunnerParams& simpleParams);

// Initializes the renderer with a simple GUI function and additional parameters.
// This will initialize the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).
void SetupFromGuiFunction(
const VoidFunction& guiFunction,
const std::string& windowTitle = "",
bool windowSizeAuto = false,
bool windowRestorePreviousGeometry = false,
const ScreenSize& windowSize = DefaultWindowSize,
float fpsIdle = 10.f
);

// Renders the current frame. Should be called regularly to maintain the application's responsiveness.
void Render();

// Tears down the renderer and releases all associated resources.
// This will release the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).
// After calling `TearDown()`, the InitFromXXX can be called with new parameters.
void TearDown();
} // namespace ManualRender

```

----

# Place widgets in a DPI-aware way
Expand Down Expand Up @@ -279,6 +356,12 @@ ImVec2 ImageProportionalSize(const ImVec2& askedSize, const ImVec2& imageSize);
```cpp
// `GetRunnerParams()`: a convenience function that will return the runnerParams
// of the current application
RunnerParams* GetRunnerParams();
// `IsUsingHelloImGui()`: returns true if the application is using HelloImGui
bool IsUsingHelloImGui();
// `FrameRate(durationForMean = 0.5)`: Returns the current FrameRate.
// May differ from ImGui::GetIO().FrameRate, since one can choose the duration
Expand Down
20 changes: 20 additions & 0 deletions docs/book/_sources/doc_params.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -830,6 +830,22 @@ See [runner_params.h](https://github.com/pthom/hello_imgui/blob/master/src/hello

```cpp

// FpsIdlingMode is an enum that describes the different modes of idling when rendering the GUI.
// - Sleep: the application will sleep when idling to reduce CPU usage.
// - EarlyReturn: rendering will return immediately when idling.
// This is specifically designed for event-driven, and real-time applications.
// Avoid using it in a tight loop without pauses, as it may cause excessive CPU consumption.
// - Auto: use platform-specific default behavior.
// On most platforms, it will sleep. On Emscripten, `Render()` will return immediately
// to avoid blocking the main thread.
// Note: you can override the default behavior by explicitly setting Sleep or EarlyReturn.
enum class FpsIdlingMode
{
Sleep,
EarlyReturn,
Auto,
};

// FpsIdling is a struct that contains Fps Idling parameters
struct FpsIdling
{
Expand Down Expand Up @@ -861,6 +877,10 @@ struct FpsIdling
// `rememberEnableIdling`: _bool, default=true_.
// If true, the last value of enableIdling is restored from the settings at startup.
bool rememberEnableIdling = false;

// `fpsIdlingMode`: _FpsIdlingMode, default=FpsIdlingMode::Automatic_.
// Sets the mode of idling when rendering the GUI (Sleep, EarlyReturn, Automatic)
FpsIdlingMode fpsIdlingMode = FpsIdlingMode::Auto;
};
```

Expand Down
1 change: 1 addition & 0 deletions docs/book/build.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,7 @@




<li class="toctree-l1 current active"><a class="current reference internal" href="#">Build instructions</a></li>
</ul>

Expand Down
87 changes: 86 additions & 1 deletion docs/book/doc_api.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,7 @@




<li class="toctree-l1"><a class="reference internal" href="build.html">Build instructions</a></li>
</ul>

Expand Down Expand Up @@ -398,6 +399,7 @@ <h2> Contents </h2>
<ul class="visible nav section-nav flex-column">
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#">API</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#run-application">Run Application</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#run-application-while-handling-the-rendering-loop">Run Application while handling the rendering loop</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#place-widgets-in-a-dpi-aware-way">Place widgets in a DPI-aware way</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#load-fonts">Load fonts</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#applications-assets">Applications assets</a><ul class="visible nav section-nav flex-column">
Expand Down Expand Up @@ -469,6 +471,81 @@ <h1>Run Application<a class="headerlink" href="#run-application" title="Permalin
the elements in the <code class="docutils literal notranslate"><span class="pre">RunnerParams</span></code> struct, or in the simpler <code class="docutils literal notranslate"><span class="pre">SimpleRunnerParams</span></code>.</p>
<p><strong>HelloImGui::GetRunnerParams()</strong> will return the runnerParams of the current application.</p>
</section>
<section class="tex2jax_ignore mathjax_ignore" id="run-application-while-handling-the-rendering-loop">
<h1>Run Application while handling the rendering loop<a class="headerlink" href="#run-application-while-handling-the-rendering-loop" title="Permalink to this heading">#</a></h1>
<p>If you want to be in control of the rendering loop, you may use the namespace <code class="docutils literal notranslate"><span class="pre">HelloImGui::ManualRender</span></code> (available since September 2024)</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span><span class="w"> </span><span class="nn">ManualRender</span>
<span class="p">{</span>
<span class="w"> </span><span class="c1">// HelloImGui::ManualRender is a namespace that groups functions, allowing fine-grained control over the rendering process:</span>
<span class="w"> </span><span class="c1">// - It is customizable like HelloImGui::Run: initialize it with `RunnerParams` or `SimpleRunnerParams`</span>
<span class="w"> </span><span class="c1">// - `ManualRender::Render()` will render the application for one frame:</span>
<span class="w"> </span><span class="c1">// - Ensure that `ManualRender::Render()` is triggered regularly (e.g., through a loop or other mechanism)</span>
<span class="w"> </span><span class="c1">// to maintain responsiveness. This method must be called on the main thread.</span>
<span class="w"> </span><span class="c1">//</span>
<span class="w"> </span><span class="c1">// A typical use case is:</span>
<span class="w"> </span><span class="c1">// C++</span>
<span class="w"> </span><span class="c1">// ```cpp</span>
<span class="w"> </span><span class="c1">// HelloImGui::RunnerParams runnerParams;</span>
<span class="w"> </span><span class="c1">// runnerParams.callbacks.ShowGui = ...; // your GUI function</span>
<span class="w"> </span><span class="c1">// // Optionally, choose between Sleep, EarlyReturn, or Auto for fps idling mode:</span>
<span class="w"> </span><span class="c1">// // runnerParams.fpsIdling.fpsIdlingMode = HelloImGui::FpsIdlingMode::Sleep; // or EarlyReturn, Auto</span>
<span class="w"> </span><span class="c1">// HelloImGui::ManualRender::SetupFromRunnerParams(runnerParams);</span>
<span class="w"> </span><span class="c1">// while (!HelloImGui::GetRunnerParams()-&gt;appShallExit)</span>
<span class="w"> </span><span class="c1">// {</span>
<span class="w"> </span><span class="c1">// HelloImGui::ManualRender::Render();</span>
<span class="w"> </span><span class="c1">// }</span>
<span class="w"> </span><span class="c1">// HelloImGui::ManualRender::TearDown();</span>
<span class="w"> </span><span class="c1">// ```</span>
<span class="w"> </span><span class="c1">// Python:</span>
<span class="w"> </span><span class="c1">// ```python</span>
<span class="w"> </span><span class="c1">// runnerParams = HelloImGui.RunnerParams()</span>
<span class="w"> </span><span class="c1">// runnerParams.callbacks.show_gui = ... # your GUI function</span>
<span class="w"> </span><span class="c1">// while not hello_imgui.get_runner_params().app_shall_exit:</span>
<span class="w"> </span><span class="c1">// hello_imgui.manual_render.render()</span>
<span class="w"> </span><span class="c1">// hello_imgui.manual_render.tear_down()</span>
<span class="w"> </span><span class="c1">// ```</span>
<span class="w"> </span><span class="c1">//</span>
<span class="w"> </span><span class="c1">// **Notes:**</span>
<span class="w"> </span><span class="c1">// 1. Depending on the configuration (`runnerParams.fpsIdling.fpsIdlingMode`), `HelloImGui` may enter</span>
<span class="w"> </span><span class="c1">// an idle state to reduce CPU usage, if no events are received (e.g., no input or interaction).</span>
<span class="w"> </span><span class="c1">// In this case, `Render()` will either sleep or return immediately.</span>
<span class="w"> </span><span class="c1">// By default,</span>
<span class="w"> </span><span class="c1">// - On Emscripten, `ManualRender::Render()` will return immediately to avoid blocking the main thread.</span>
<span class="w"> </span><span class="c1">// - On other platforms, it will sleep</span>
<span class="w"> </span><span class="c1">// 2. If initialized with `RunnerParams`, a copy of the `RunnerParams` will be made</span>
<span class="w"> </span><span class="c1">// (which can be accessed with `HelloImGui::GetRunnerParams()`).</span>

<span class="w"> </span><span class="c1">// Initializes the rendering with the full customizable `RunnerParams`.</span>
<span class="w"> </span><span class="c1">// This will initialize the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).</span>
<span class="w"> </span><span class="c1">// A distinct copy of `RunnerParams` is stored internally.</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">SetupFromRunnerParams</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">RunnerParams</span><span class="o">&amp;</span><span class="w"> </span><span class="n">runnerParams</span><span class="p">);</span>

<span class="w"> </span><span class="c1">// Initializes the rendering with `SimpleRunnerParams`.</span>
<span class="w"> </span><span class="c1">// This will initialize the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">SetupFromSimpleRunnerParams</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">SimpleRunnerParams</span><span class="o">&amp;</span><span class="w"> </span><span class="n">simpleParams</span><span class="p">);</span>

<span class="w"> </span><span class="c1">// Initializes the renderer with a simple GUI function and additional parameters.</span>
<span class="w"> </span><span class="c1">// This will initialize the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="n">SetupFromGuiFunction</span><span class="p">(</span>
<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">VoidFunction</span><span class="o">&amp;</span><span class="w"> </span><span class="n">guiFunction</span><span class="p">,</span>
<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&amp;</span><span class="w"> </span><span class="n">windowTitle</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="n">windowSizeAuto</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">false</span><span class="p">,</span>
<span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="n">windowRestorePreviousGeometry</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">false</span><span class="p">,</span>
<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">ScreenSize</span><span class="o">&amp;</span><span class="w"> </span><span class="n">windowSize</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">DefaultWindowSize</span><span class="p">,</span>
<span class="w"> </span><span class="kt">float</span><span class="w"> </span><span class="n">fpsIdle</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">10.f</span>
<span class="w"> </span><span class="p">);</span>

<span class="w"> </span><span class="c1">// Renders the current frame. Should be called regularly to maintain the application&#39;s responsiveness.</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Render</span><span class="p">();</span>

<span class="w"> </span><span class="c1">// Tears down the renderer and releases all associated resources.</span>
<span class="w"> </span><span class="c1">// This will release the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).</span>
<span class="w"> </span><span class="c1">// After calling `TearDown()`, the InitFromXXX can be called with new parameters.</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">TearDown</span><span class="p">();</span>
<span class="p">}</span><span class="w"> </span><span class="c1">// namespace ManualRender</span>
</pre></div>
</div>
</section>
<hr class="docutils" />
<section class="tex2jax_ignore mathjax_ignore" id="place-widgets-in-a-dpi-aware-way">
<h1>Place widgets in a DPI-aware way<a class="headerlink" href="#place-widgets-in-a-dpi-aware-way" title="Permalink to this heading">#</a></h1>
Expand Down Expand Up @@ -708,7 +785,14 @@ <h2>Display images from assets<a class="headerlink" href="#display-images-from-a
<hr class="docutils" />
<section class="tex2jax_ignore mathjax_ignore" id="utility-functions">
<h1>Utility functions<a class="headerlink" href="#utility-functions" title="Permalink to this heading">#</a></h1>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// `FrameRate(durationForMean = 0.5)`: Returns the current FrameRate.</span>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// `GetRunnerParams()`: a convenience function that will return the runnerParams</span>
<span class="c1">// of the current application</span>
<span class="w"> </span><span class="n">RunnerParams</span><span class="o">*</span><span class="w"> </span><span class="nf">GetRunnerParams</span><span class="p">();</span>

<span class="c1">// `IsUsingHelloImGui()`: returns true if the application is using HelloImGui</span>
<span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="nf">IsUsingHelloImGui</span><span class="p">();</span>

<span class="c1">// `FrameRate(durationForMean = 0.5)`: Returns the current FrameRate.</span>
<span class="c1">// May differ from ImGui::GetIO().FrameRate, since one can choose the duration</span>
<span class="c1">// for the calculation of the mean value of the fps</span>
<span class="c1">// Returns the current FrameRate. May differ from ImGui::GetIO().FrameRate,</span>
Expand Down Expand Up @@ -1129,6 +1213,7 @@ <h2>Fine tune DPI Handling<a class="headerlink" href="#fine-tune-dpi-handling" t
<ul class="visible nav section-nav flex-column">
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#">API</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#run-application">Run Application</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#run-application-while-handling-the-rendering-loop">Run Application while handling the rendering loop</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#place-widgets-in-a-dpi-aware-way">Place widgets in a DPI-aware way</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#load-fonts">Load fonts</a></li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#applications-assets">Applications assets</a><ul class="visible nav section-nav flex-column">
Expand Down
Loading

0 comments on commit 52e4b37

Please sign in to comment.