Skip to content

Commit

Permalink
Update docs / 2024-10-02 / 19:34:02
Browse files Browse the repository at this point in the history
  • Loading branch information
@pthom
pthom committed Oct 2, 2024
1 parent 86924b1 commit c318754
Show file tree
Hide file tree
Showing 10 changed files with 3 additions and 186 deletions.
67 changes: 0 additions & 67 deletions docs/book/_sources/doc_api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,67 +24,6 @@ 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 class `HelloImGui::Renderer` (available since September 2024)

```cpp

// HelloImGui::Renderer is an alternative to HelloImGui::Run, allowing fine-grained control over the rendering process.
// - It is customizable like HelloImGui::Run: construct it with `RunnerParams` or `SimpleRunnerParams`
// - `Render()` will render the application for one frame:
// Ensure that `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:
// ```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
// Renderer renderer(runnerParams); // note: a distinct copy of the `RunnerParams` will be stored inside the HelloImGui::GetRunnerParams()
// while (! HelloImGui::GetRunnerParams()->appShallExit)
// {
// renderer.Render();
// }
// ```
//
// **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, `Render()` will return immediately to avoid blocking the main thread.
// - On other platforms, it will sleep
// 2. Only one instance of `Renderer` can exist at a time.
// 3. If constructed with `RunnerParams`, a copy of the `RunnerParams` will be made (which you can access with `GetRunnerParams())`.
class Renderer
{
public:
// Initializes with the full customizable `RunnerParams` to set up the application.
// Nb: a distinct copy of the `RunnerParams` will be made, and you can access it with `GetRunnerParams()`.
Renderer(const RunnerParams& runnerParams);

// Initializes with SimpleRunnerParams.
Renderer(const SimpleRunnerParams& simpleParams);

// Initializes with a simple GUI function and additional parameters.
Renderer(
const VoidFunction &guiFunction,
const std::string &windowTitle = "",
bool windowSizeAuto = false,
bool windowRestorePreviousGeometry = false,
const ScreenSize &windowSize = DefaultWindowSize,
float fpsIdle = 10.f
);

// Render the current frame (or return immediately if in idle state).
void Render();

// Destructor (automatically tears down HelloImGui).
~Renderer();
};
```
----

# Place widgets in a DPI-aware way
Expand Down Expand Up @@ -340,12 +279,6 @@ 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: 0 additions & 20 deletions docs/book/_sources/doc_params.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -830,22 +830,6 @@ 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 @@ -877,10 +861,6 @@ 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: 0 additions & 1 deletion docs/book/build.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,6 @@




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

Expand Down
72 changes: 1 addition & 71 deletions docs/book/doc_api.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,6 @@




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

Expand Down Expand Up @@ -399,7 +398,6 @@ <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 @@ -471,66 +469,6 @@ <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 class <code class="docutils literal notranslate"><span class="pre">HelloImGui::Renderer</span></code> (available since September 2024)</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// HelloImGui::Renderer is an alternative to HelloImGui::Run, allowing fine-grained control over the rendering process.</span>
<span class="c1">// - It is customizable like HelloImGui::Run: construct it with `RunnerParams` or `SimpleRunnerParams`</span>
<span class="c1">// - `Render()` will render the application for one frame:</span>
<span class="c1">// Ensure that `Render()` is triggered regularly (e.g., through a loop or other mechanism) to maintain responsiveness.</span>
<span class="c1">// This method must be called on the main thread.</span>
<span class="c1">//</span>
<span class="c1">// A typical use case is:</span>
<span class="c1">// ```cpp</span>
<span class="c1">// HelloImGui::RunnerParams runnerParams;</span>
<span class="c1">// runnerParams.callbacks.ShowGui = ...; // your GUI function</span>
<span class="c1">// // Optionally, choose between Sleep, EarlyReturn, or Auto for fps idling mode:</span>
<span class="c1">// // runnerParams.fpsIdling.fpsIdlingMode = HelloImGui::FpsIdlingMode::Sleep; // or EarlyReturn, Auto</span>
<span class="c1">// Renderer renderer(runnerParams); // note: a distinct copy of the `RunnerParams` will be stored inside the HelloImGui::GetRunnerParams()</span>
<span class="c1">// while (! HelloImGui::GetRunnerParams()-&gt;appShallExit)</span>
<span class="c1">// {</span>
<span class="c1">// renderer.Render();</span>
<span class="c1">// }</span>
<span class="c1">// ```</span>
<span class="c1">//</span>
<span class="c1">// **Notes:**</span>
<span class="c1">// 1. Depending on the configuration (`runnerParams.fpsIdling.fpsIdlingMode`), `HelloImGui` may enter an idle state to</span>
<span class="c1">// reduce CPU usage, if no events are received (e.g., no input or interaction).</span>
<span class="c1">// In this case, `Render()` will either sleep or return immediately.</span>
<span class="c1">// By default,</span>
<span class="c1">// - On Emscripten, `Render()` will return immediately to avoid blocking the main thread.</span>
<span class="c1">// - On other platforms, it will sleep</span>
<span class="c1">// 2. Only one instance of `Renderer` can exist at a time.</span>
<span class="c1">// 3. If constructed with `RunnerParams`, a copy of the `RunnerParams` will be made (which you can access with `GetRunnerParams())`.</span>
<span class="k">class</span><span class="w"> </span><span class="nc">Renderer</span>
<span class="p">{</span>
<span class="k">public</span><span class="o">:</span>
<span class="w"> </span><span class="c1">// Initializes with the full customizable `RunnerParams` to set up the application.</span>
<span class="w"> </span><span class="c1">// Nb: a distinct copy of the `RunnerParams` will be made, and you can access it with `GetRunnerParams()`.</span>
<span class="w"> </span><span class="n">Renderer</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 with SimpleRunnerParams.</span>
<span class="w"> </span><span class="n">Renderer</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 with a simple GUI function and additional parameters.</span>
<span class="w"> </span><span class="n">Renderer</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="w"> </span><span class="o">&amp;</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="w"> </span><span class="o">&amp;</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="w"> </span><span class="o">&amp;</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">// Render the current frame (or return immediately if in idle state).</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">// Destructor (automatically tears down HelloImGui).</span>
<span class="w"> </span><span class="o">~</span><span class="n">Renderer</span><span class="p">();</span>
<span class="p">};</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 @@ -770,14 +708,7 @@ <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">// `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>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></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 @@ -1198,7 +1129,6 @@ <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
23 changes: 1 addition & 22 deletions docs/book/doc_params.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,6 @@




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

Expand Down Expand Up @@ -1257,23 +1256,7 @@ <h2>Default window types<a class="headerlink" href="#default-window-types" title
<section class="tex2jax_ignore mathjax_ignore" id="fps-idling">
<h1>Fps Idling<a class="headerlink" href="#fps-idling" title="Permalink to this heading">#</a></h1>
<p>See <a class="reference external" href="https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_params.h">runner_params.h</a>.</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// FpsIdlingMode is an enum that describes the different modes of idling when rendering the GUI.</span>
<span class="c1">// - Sleep: the application will sleep when idling to reduce CPU usage.</span>
<span class="c1">// - EarlyReturn: rendering will return immediately when idling.</span>
<span class="c1">// This is specifically designed for event-driven, and real-time applications.</span>
<span class="c1">// Avoid using it in a tight loop without pauses, as it may cause excessive CPU consumption.</span>
<span class="c1">// - Auto: use platform-specific default behavior.</span>
<span class="c1">// On most platforms, it will sleep. On Emscripten, `Render()` will return immediately</span>
<span class="c1">// to avoid blocking the main thread.</span>
<span class="c1">// Note: you can override the default behavior by explicitly setting Sleep or EarlyReturn.</span>
<span class="k">enum</span><span class="w"> </span><span class="k">class</span><span class="w"> </span><span class="nc">FpsIdlingMode</span>
<span class="p">{</span>
<span class="w"> </span><span class="n">Sleep</span><span class="p">,</span>
<span class="w"> </span><span class="n">EarlyReturn</span><span class="p">,</span>
<span class="w"> </span><span class="n">Auto</span><span class="p">,</span>
<span class="p">};</span>

<span class="c1">// FpsIdling is a struct that contains Fps Idling parameters</span>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// FpsIdling is a struct that contains Fps Idling parameters</span>
<span class="k">struct</span><span class="w"> </span><span class="nc">FpsIdling</span>
<span class="p">{</span>
<span class="w"> </span><span class="c1">// `fpsIdle`: _float, default=9_.</span>
Expand Down Expand Up @@ -1304,10 +1287,6 @@ <h1>Fps Idling<a class="headerlink" href="#fps-idling" title="Permalink to this
<span class="w"> </span><span class="c1">// `rememberEnableIdling`: _bool, default=true_.</span>
<span class="w"> </span><span class="c1">// If true, the last value of enableIdling is restored from the settings at startup.</span>
<span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="n">rememberEnableIdling</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="c1">// `fpsIdlingMode`: _FpsIdlingMode, default=FpsIdlingMode::Automatic_.</span>
<span class="w"> </span><span class="c1">// Sets the mode of idling when rendering the GUI (Sleep, EarlyReturn, Automatic)</span>
<span class="w"> </span><span class="n">FpsIdlingMode</span><span class="w"> </span><span class="n">fpsIdlingMode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">FpsIdlingMode</span><span class="o">::</span><span class="n">Auto</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
Expand Down
1 change: 0 additions & 1 deletion docs/book/genindex.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,6 @@




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

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




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

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




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

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




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

Expand Down
2 changes: 1 addition & 1 deletion docs/book/searchindex.js
View file

Large diffs are not rendered by default.

0 comments on commit c318754

Please sign in to comment.